docs: add Docker troubleshooting guide and link in README. Solves issue #32
This commit is contained in:
czlonkowski
313
docs/DOCKER_TROUBLESHOOTING.md
Normal file
313
docs/DOCKER_TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,313 @@
|
||||
# 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](#common-issues)
|
||||
- [502 Bad Gateway Errors](#502-bad-gateway-errors)
|
||||
- [Container Name Conflicts](#container-name-conflicts)
|
||||
- [n8n API Connection Issues](#n8n-api-connection-issues)
|
||||
- [Docker Networking](#docker-networking)
|
||||
- [Quick Solutions](#quick-solutions)
|
||||
- [Debugging Steps](#debugging-steps)
|
||||
|
||||
## Common 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:**
|
||||
|
||||
#### 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 Name Conflicts
|
||||
|
||||
**Symptoms:**
|
||||
- Error: "Container with name '/n8n-mcp-container' already exists"
|
||||
- Claude Desktop shows duplicate containers
|
||||
|
||||
**Root Cause:** Claude Desktop bug that spawns containers twice.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Remove container name (Recommended):**
|
||||
```json
|
||||
{
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "-i", "--rm",
|
||||
// Remove: "--name", "n8n-mcp-container",
|
||||
"ghcr.io/czlonkowski/n8n-mcp:latest"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
2. **Manual cleanup when it happens:**
|
||||
```bash
|
||||
docker rm -f n8n-mcp-container
|
||||
```
|
||||
|
||||
3. **Use HTTP mode instead** (avoids the issue entirely)
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
3. **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
|
||||
|
||||
| Scenario | Use This URL | Why |
|
||||
|----------|--------------|-----|
|
||||
| n8n on host, n8n-mcp in Docker | `http://host.docker.internal:5678` | Docker can't reach host's localhost |
|
||||
| Both in same Docker network | `http://container-name:5678` | Direct container-to-container |
|
||||
| n8n behind reverse proxy | `http://your-domain.com` | Use public URL |
|
||||
| Local development | `http://YOUR_LOCAL_IP:5678` | Use 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](https://github.com/czlonkowski/n8n-mcp/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
|
||||
```
|
||||
Reference in New Issue
Block a user