Troubleshooting Guide

Docker Issues

502 Bad Gateway Errors

Symptoms:

n8n_health_check returns 502 error
All n8n management API calls fail
n8n web UI is accessible but API is not

Root Cause: Network connectivity issues between n8n-MCP container and n8n instance.

Solutions

When n8n runs in Docker on same machine

Use Docker’s special hostnames:

{
  "N8N_API_URL": "http://host.docker.internal:5678"
}

Alternative hostnames:

host.docker.internal (Docker Desktop on macOS/Windows)
172.17.0.1 (Default Docker bridge IP on Linux)
Your machine’s IP address (e.g., 192.168.1.100)

When both containers are in same Docker network

# Create shared network
docker network create n8n-network

# Run n8n
docker run -d --name n8n --network n8n-network n8nio/n8n

# Configure n8n-mcp
{
  "N8N_API_URL": "http://n8n:5678"
}

For Docker Compose

services:
  n8n:
    image: n8nio/n8n
    networks:
      - n8n-net
    ports:
      - "5678:5678"
  
  n8n-mcp:
    image: ghcr.io/czlonkowski/n8n-mcp:latest
    environment:
      N8N_API_URL: http://n8n:5678
    networks:
      - n8n-net

networks:
  n8n-net:

Container Cleanup Issues

Symptoms:

Containers accumulate after Claude Desktop restarts
Containers show as “unhealthy”
--rm flag doesn’t work as expected

Solution: Update to v2.7.20+ and use --init flag:

{
  "command": "docker",
  "args": [
    "run", "-i", "--rm", "--init",
    "ghcr.io/czlonkowski/n8n-mcp:latest"
  ]
}

Manual cleanup:

# Remove stopped containers
docker ps -a | grep n8n-mcp | grep Exited | awk '{print $1}' | xargs -r docker rm

Webhooks to Local n8n Fail

Symptoms:

n8n_test_workflow fails with “SSRF protection” error
Error: “Localhost access is blocked”

Root Cause: Default strict SSRF protection blocks localhost.Solution: Use moderate security mode for local development:

{
  "environment": {
    "WEBHOOK_SECURITY_MODE": "moderate"
  }
}

Security Modes:

strict (default): Blocks localhost + private IPs (production)
moderate: Allows localhost, blocks private IPs (local dev)
permissive: Allows localhost + private IPs (testing only)

Always use strict mode in production.

Custom Database Path Not Working

Symptoms:

NODE_DB_PATH environment variable ignored
Database always at /app/data/nodes.db

Solution: Update to v2.7.16+ and ensure path ends with .db:

{
  "environment": {
    "NODE_DB_PATH": "/app/data/custom/my-nodes.db"
  },
  "volumes": [
    "n8n-mcp-data:/app/data"
  ]
}

Docker Configuration File Issues

Symptoms:

Config file mounted but variables not set
“Permission denied” errors

Solutions:

Mount correctly:

docker run -v $(pwd)/config.json:/app/config.json:ro ...

Validate JSON:

cat config.json | jq .

Check logs:

docker logs n8n-mcp | grep -i config

Common issues:

Invalid JSON syntax
Wrong mount path (must be /app/config.json)
File not readable
Dangerous variables blocked (PATH, LD_PRELOAD)

Workflow Validation Issues

fixedCollection Errors

Error: propertyValues[itemName] is not iterableCause: Incorrect fixedCollection structure (object instead of array)Example:

Bad

{
  "conditions": {
    "string": { "value1": "test" }  // ❌ Object
  }
}

Good

{
  "conditions": {
    "string": [  // ✅ Array
      {
        "value1": "={{$json.field}}",
        "operation": "equals",
        "value2": "test"
      }
    ]
  }
}

Solution: Validation provides auto-fix:

{
  "autofix": {
    "conditions": {
      "string": [{ /* corrected structure */ }]
    }
  }
}

Invalid Resource/Operation

Error: Invalid resource or operation valueCause: Typo or incorrect value for node’s resource/operationSolution: Validation suggests similar values:

{
  "errors": [
    {
      "property": "resource",
      "message": "Invalid resource 'mesage'. Did you mean 'message'?",
      "fix": "Change resource to 'message'"
    }
  ]
}

Missing Required Fields

Error: Required property missingCause: Configuration incomplete for the operationSolution:

Use mode: 'minimal' to quickly check required fields:

validate_node({
  nodeType: 'n8n-nodes-base.slack',
  config: { resource: 'message', operation: 'post' },
  mode: 'minimal'
})

Get operation details:

get_node({
  nodeType: 'n8n-nodes-base.slack',
  mode: 'search_properties',
  propertyQuery: 'channel'
})

Use full validation for guidance:

validate_node({
  mode: 'full',
  profile: 'runtime'
})

Type Mismatch Errors

Error: Invalid type for propertyExamples:

Bad

{
  "timeout": "10",  // ❌ String instead of number
  "enabled": "true" // ❌ String instead of boolean
}

Good

{
  "timeout": 10,    // ✅ Number
  "enabled": true   // ✅ Boolean
}

Solution: Check property type in node details:

get_node({
  nodeType: 'n8n-nodes-base.httpRequest',
  detail: 'standard'
})

Connection Issues

Wrong Connection Syntax

Error: Source node not found or connection failsCause: Incorrect connection syntax for addConnectionWrong formats:

Object Format (fails)

{
  "type": "addConnection",
  "connection": {
    "source": { "nodeId": "node-1" }
  }
}

Combined String (fails)

{
  "type": "addConnection",
  "source": "node-1:main:0"
}

Correct format:

Four String Parameters

{
  "type": "addConnection",
  "source": "source-node-name",
  "target": "target-node-name",
  "sourcePort": "main",
  "targetPort": "main"
}

IF Node Routing Issues

Problem: Both branches connect to wrong outputsSolution: Use branch parameter:

{
  "operations": [
    {
      "type": "addConnection",
      "source": "If Node",
      "target": "True Handler",
      "sourcePort": "main",
      "targetPort": "main",
      "branch": "true"
    },
    {
      "type": "addConnection",
      "source": "If Node",
      "target": "False Handler",
      "sourcePort": "main",
      "targetPort": "main",
      "branch": "false"
    }
  ]
}

Circular Dependencies

Error: Connection would create a loopCause: Attempting to create a connection that loops backSolution:

Redesign workflow to eliminate loop
Use Split in Batches node for iteration
Consider using separate workflows connected by webhooks

AI Agent Issues

Missing Language Model

Error: AI Agent missing language model connectionSolution:

{
  "connections": {
    "OpenAI Chat Model": {
      "ai_languageModel": [[
        {
          "node": "AI Agent",
          "type": "ai_languageModel",
          "index": 0
        }
      ]]
    }
  }
}

Tool Not Accessible

Error: Tool node not connected to agentSolution:

{
  "connections": {
    "HTTP Request Tool": {
      "ai_tool": [[
        {
          "node": "AI Agent",
          "type": "ai_tool",
          "index": 0
        }
      ]]
    }
  }
}

Streaming Conflicts

Warning: Streaming incompatible with output parserSolution:

Disable streaming in language model: streaming: false
OR remove output parser if streaming is required

Template Issues

Template Validation Fails

Issue: Template doesn’t work with current n8n versionSolution:

Validate template:

get_template(templateId, { mode: 'full' })
validate_workflow(workflow)

Fix issues from validation
Use auto-fix deployment:

n8n_deploy_template({
  templateId: templateId,
  autofix: true
})

Missing Template Attribution

Requirement: Templates must include author creditSolution:Always provide:

Based on template by **[Author Name]** (@username).
View at: https://n8n.io/workflows/[id]

Performance Issues

Validation Too Slow

Problem: Full validation takes too longSolution: Use progressive validation:

// Step 1: Quick check (< 100ms)
validate_node({ mode: 'minimal' })

// Step 2: If errors, full validation
if (hasErrors) {
  validate_node({ mode: 'full', profile: 'runtime' })
}

Too Many Tool Calls

Problem: Excessive serial tool callsSolution: Execute independent operations in parallel:

// ✅ Parallel execution
search_nodes({ query: 'slack' })
search_nodes({ query: 'webhook' })
search_templates({ task: 'slack_integration' })

// All execute simultaneously

Large Workflow Updates

Problem: Full workflow updates use too many tokensSolution: Use diff operations:

// Instead of sending entire workflow:
n8n_update_partial_workflow({
  id: 'workflow-id',
  operations: [
    { type: 'updateNode', nodeName: 'Node1', changes: {...} }
  ]
})

80-90% token reduction vs full updates.

Debugging Steps

Enable Debug Logging

{
  "environment": {
    "LOG_LEVEL": "debug",
    "DEBUG_MCP": "true"
  }
}

Check Docker Logs

# n8n-mcp logs
docker logs $(docker ps -q -f ancestor=ghcr.io/czlonkowski/n8n-mcp:latest)

# n8n logs
docker logs n8n

Test Connectivity

# From n8n-mcp container
docker run --rm ghcr.io/czlonkowski/n8n-mcp:latest \
  sh -c "apk add curl && curl -v http://host.docker.internal:5678/api/v1/workflows"

Validate Environment

# Check environment variables
docker run --rm ghcr.io/czlonkowski/n8n-mcp:latest \
  sh -c "env | grep N8N"

Platform-Specific Notes

Docker Desktop (macOS/Windows)

host.docker.internal works out of the box
Ensure Docker Desktop is running
Check Docker Desktop → Settings → Resources → Network

Linux

host.docker.internal requires Docker 20.10+
Alternative: Use --add-host=host.docker.internal:host-gateway
Or use Docker bridge IP: 172.17.0.1

Windows with WSL2

Use host.docker.internal or WSL2 IP
Check firewall rules for port 5678
Ensure n8n binds to 0.0.0.0 not 127.0.0.1

Getting Help

GitHub Issues

Report bugs and request features

Discussions

Ask questions and share solutions

Documentation

Complete n8n-MCP documentation

Docker Guide

Detailed Docker troubleshooting

Useful Commands

Cleanup

# Remove all n8n-mcp containers
docker rm -f $(docker ps -aq -f ancestor=ghcr.io/czlonkowski/n8n-mcp:latest)

Test API

# Test n8n API with curl
curl -H "X-N8N-API-KEY: your-key" http://localhost:5678/api/v1/workflows

Debug Session

# Run interactive debug session
docker run -it --rm \
  -e LOG_LEVEL=debug \
  -e N8N_API_URL=http://host.docker.internal:5678 \
  -e N8N_API_KEY=your-key \
  ghcr.io/czlonkowski/n8n-mcp:latest \
  sh

Network Check

# Test Docker networking
docker run --rm alpine ping -c 4 host.docker.internal

Next Steps

Building Workflows

Learn the complete workflow building process

Validation Strategies

Understand validation modes and profiles

Batch Operations

Efficient workflow updates

AI Agent Workflows

Building AI Agent workflows

Get Started

Deployment

Configuration

IDE Integration

Core Concepts

Guides

Troubleshooting Guide

Docker Issues

Solutions

When n8n runs in Docker on same machine

When both containers are in same Docker network

For Docker Compose

Workflow Validation Issues

Connection Issues

AI Agent Issues

Template Issues

Performance Issues

Debugging Steps

Platform-Specific Notes

Docker Desktop (macOS/Windows)

Linux

Windows with WSL2

Getting Help

GitHub Issues

Discussions

Documentation

Docker Guide

Useful Commands

Next Steps

Building Workflows

Validation Strategies

Batch Operations

AI Agent Workflows

Build docs developers (and LLMs) love

Get Started

Deployment

Configuration

IDE Integration

Core Concepts

Guides

​Docker Issues

​Solutions

​When n8n runs in Docker on same machine

​When both containers are in same Docker network

​For Docker Compose

​Workflow Validation Issues

​Connection Issues

​AI Agent Issues

​Template Issues

​Performance Issues

​Debugging Steps

​Platform-Specific Notes

​Docker Desktop (macOS/Windows)

​Linux

​Windows with WSL2

​Getting Help

GitHub Issues

Discussions

Documentation

Docker Guide

​Useful Commands

​Next Steps

Building Workflows

Validation Strategies

Batch Operations

AI Agent Workflows

Build docs developers (and LLMs) love

Docker Issues

Solutions

When n8n runs in Docker on same machine

When both containers are in same Docker network

For Docker Compose

Workflow Validation Issues

Connection Issues

AI Agent Issues

Template Issues

Performance Issues

Debugging Steps

Platform-Specific Notes

Docker Desktop (macOS/Windows)

Linux

Windows with WSL2

Getting Help

Useful Commands

Next Steps