ContextQMD
Back to N8n Mcp

Docker Troubleshooting Guide

docs/DOCKER_TROUBLESHOOTING.md

2.50.410.0 KB
Original Source

Docker Troubleshooting Guide

This guide helps resolve common issues when running n8n-mcp with Docker, especially when connecting to n8n instances.

Table of Contents

Common Issues

Docker Configuration File Not Working (v2.8.2+)

Symptoms:

  • Config file mounted but environment variables not set
  • Container starts but ignores configuration
  • Getting "permission denied" errors

Solutions:

  1. Ensure file is mounted correctly:
bash
# Correct - mount as read-only
docker run -v $(pwd)/config.json:/app/config.json:ro ...

# Check if file is accessible
docker exec n8n-mcp cat /app/config.json
  1. Verify JSON syntax:
bash
# Validate JSON file
cat config.json | jq .
  1. Check Docker logs for parsing errors:
bash
docker logs n8n-mcp | grep -i config
  1. Common issues:
  • Invalid JSON syntax (use a JSON validator)
  • File permissions (should be readable)
  • Wrong mount path (must be /app/config.json)
  • Dangerous variables blocked (PATH, LD_PRELOAD, etc.)

Custom Database Path Not Working (v2.7.16+)

Symptoms:

  • NODE_DB_PATH environment variable is set but ignored
  • Database always created at /app/data/nodes.db
  • Custom path setting has no effect

Root Cause: Fixed in v2.7.16. Earlier versions had hardcoded paths in docker-entrypoint.sh.

Solutions:

  1. Update to v2.7.16 or later:
bash
docker pull ghcr.io/czlonkowski/n8n-mcp:latest
  1. Ensure path ends with .db:
bash
# Correct
NODE_DB_PATH=/app/data/custom/my-nodes.db

# Incorrect (will be rejected)
NODE_DB_PATH=/app/data/custom/my-nodes
  1. Use path within mounted volume for persistence:
yaml
services:
  n8n-mcp:
    environment:
      NODE_DB_PATH: /app/data/custom/nodes.db
    volumes:
      - n8n-mcp-data:/app/data  # Ensure parent directory is mounted

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:

1. When n8n runs in Docker on same machine

Use Docker's special hostnames instead of localhost:

json
{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "N8N_API_URL=http://host.docker.internal:5678",
        "-e", "N8N_API_KEY=your-api-key",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

Alternative hostnames to try:

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

2. When both containers are in same Docker network

bash
# Create a shared network
docker network create n8n-network

# Run n8n in the network
docker run -d --name n8n --network n8n-network -p 5678:5678 n8nio/n8n

# Configure n8n-mcp to use container name
json
{
  "N8N_API_URL": "http://n8n:5678"
}

3. For Docker Compose setups

yaml
# docker-compose.yml
services:
  n8n:
    image: n8nio/n8n
    container_name: n8n
    networks:
      - n8n-net
    ports:
      - "5678:5678"
  
  n8n-mcp:
    image: ghcr.io/czlonkowski/n8n-mcp:latest
    environment:
      N8N_API_URL: http://n8n:5678
      N8N_API_KEY: ${N8N_API_KEY}
    networks:
      - n8n-net

networks:
  n8n-net:
    driver: bridge

Container Cleanup Issues (Fixed in v2.7.20+)

Symptoms:

  • Containers accumulate after Claude Desktop restarts
  • Containers show as "unhealthy" but don't clean up
  • --rm flag doesn't work as expected

Root Cause: Fixed in v2.7.20 - containers weren't handling termination signals properly.

Solutions:

  1. Update to v2.7.20+ and use --init flag (Recommended):
json
{
  "command": "docker",
  "args": [
    "run", "-i", "--rm", "--init",
    "ghcr.io/czlonkowski/n8n-mcp:latest"
  ]
}
  1. Manual cleanup of old containers:
bash
# Remove all stopped n8n-mcp containers
docker ps -a | grep n8n-mcp | grep Exited | awk '{print $1}' | xargs -r docker rm
  1. For versions before 2.7.20:
  • Manually clean up containers periodically
  • Consider using HTTP mode instead

Webhooks to Local n8n Fail (v2.16.3+)

Symptoms:

  • n8n_trigger_webhook_workflow fails with "SSRF protection" error
  • Error message: "SSRF protection: Localhost access is blocked"
  • Webhooks work from n8n UI but not from n8n-MCP

Root Cause: Default strict SSRF protection blocks localhost access to prevent attacks.

Solution: Use moderate security mode for local development

bash
# For Docker run
docker run -d \
  --name n8n-mcp \
  -e MCP_MODE=http \
  -e AUTH_TOKEN=your-token \
  -e WEBHOOK_SECURITY_MODE=moderate \
  -p 3000:3000 \
  ghcr.io/czlonkowski/n8n-mcp:latest

# For Docker Compose - add to environment:
services:
  n8n-mcp:
    environment:
      WEBHOOK_SECURITY_MODE: moderate

Security Modes Explained:

  • strict (default): Blocks localhost + private IPs + cloud metadata (production)
  • moderate: Allows localhost, blocks private IPs + cloud metadata (local development)
  • permissive: Allows localhost + private IPs, blocks cloud metadata (testing only)

Important: Always use strict mode in production. Cloud metadata is blocked in all modes.

n8n API Connection Issues

Symptoms:

  • API calls fail but n8n web UI works
  • Authentication errors
  • API endpoints return 404

Solutions:

  1. Verify n8n API is enabled:

    • Check n8n settings → REST API is enabled
    • Ensure API key is valid and not expired

  2. Test API directly:

bash
# From host machine
curl -H "X-N8N-API-KEY: your-key" http://localhost:5678/api/v1/workflows

# From inside Docker container
docker run --rm curlimages/curl \
  -H "X-N8N-API-KEY: your-key" \
  http://host.docker.internal:5678/api/v1/workflows
  1. Check n8n environment variables:
yaml
environment:
  - N8N_BASIC_AUTH_ACTIVE=true
  - N8N_BASIC_AUTH_USER=user
  - N8N_BASIC_AUTH_PASSWORD=password

Docker Networking

Understanding Docker Network Modes

ScenarioUse This URLWhy
n8n on host, n8n-mcp in Dockerhttp://host.docker.internal:5678Docker can't reach host's localhost
Both in same Docker networkhttp://container-name:5678Direct container-to-container
n8n behind reverse proxyhttp://your-domain.comUse public URL
Local developmenthttp://YOUR_LOCAL_IP:5678Use machine's IP address

Finding Your Configuration

bash
# Check if n8n is running in Docker
docker ps | grep n8n

# Find Docker network
docker network ls

# Get container details
docker inspect n8n | grep NetworkMode

# Find your local IP
# macOS/Linux
ifconfig | grep "inet " | grep -v 127.0.0.1

# Windows
ipconfig | findstr IPv4

Quick Solutions

Solution 1: Use Host Network (Linux only)

json
{
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "--network", "host",
    "-e", "N8N_API_URL=http://localhost:5678",
    "ghcr.io/czlonkowski/n8n-mcp:latest"
  ]
}

Solution 2: Use Your Machine's IP

json
{
  "N8N_API_URL": "http://192.168.1.100:5678"  // Replace with your IP
}

Solution 3: HTTP Mode Deployment

Deploy n8n-mcp as HTTP server to avoid stdio/Docker issues:

bash
# Start HTTP server
docker run -d \
  -p 3000:3000 \
  -e MCP_MODE=http \
  -e AUTH_TOKEN=your-token \
  -e N8N_API_URL=http://host.docker.internal:5678 \
  -e N8N_API_KEY=your-n8n-key \
  ghcr.io/czlonkowski/n8n-mcp:latest

# Configure Claude with mcp-remote

Debugging Steps

1. Enable Debug Logging

json
{
  "env": {
    "LOG_LEVEL": "debug",
    "DEBUG_MCP": "true"
  }
}

2. Test Connectivity

bash
# Test 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"

3. Check Docker Logs

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

# View n8n logs
docker logs n8n

4. Validate Environment

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

5. Network Diagnostics

bash
# Check Docker networks
docker network inspect bridge

# Test DNS resolution
docker run --rm busybox nslookup host.docker.internal

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 the 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

Still Having Issues?

  1. Check n8n logs for API-related errors
  2. Verify firewall/security isn't blocking connections
  3. Try simpler setup - Run n8n-mcp on host instead of Docker
  4. Report issue with debug logs at GitHub Issues

Useful Commands

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

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

# 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

# Check container networking
docker run --rm alpine ping -c 4 host.docker.internal