Homelab/docs/guides/n8n_troubleshooting.md

n8n Troubleshooting Guide

Connection Loss / Frequent Disconnects

Problem

n8n UI shows "Connection Lost" errors and logs contain:

ValidationError: The 'X-Forwarded-For' header is set but the Express 'trust proxy' setting is false

Root Cause

n8n is behind Traefik reverse proxy which sets X-Forwarded-For headers, but n8n's Express app doesn't trust the proxy by default. This breaks rate limiting and causes connection issues.

Solution

Add these environment variables to n8n configuration:

environment:
  - N8N_SECURE_COOKIE=false  # Required when TLS is terminated at reverse proxy
  - N8N_METRICS=true         # Enable metrics endpoint

Status: ✅ Fixed in current configuration

---

Deprecation Warnings

1. SQLite Pool Size

Warning:

Running SQLite without a pool of read connections is deprecated

Fix:

- DB_SQLITE_POOL_SIZE=10

2. Task Runners

Warning:

Running n8n without task runners is deprecated

Fix:

- N8N_RUNNERS_ENABLED=true

3. Environment Variable Access

Warning:

The default value of N8N_BLOCK_ENV_ACCESS_IN_NODE will change from false to true

Fix:

- N8N_BLOCK_ENV_ACCESS_IN_NODE=false  # Allow Code Node to access env vars

4. Git Node Bare Repos

Warning:

Support for bare repositories in the Git Node will be removed

Fix:

- N8N_GIT_NODE_DISABLE_BARE_REPOS=true

Status: ✅ All fixed in current configuration

---

Resource Issues

Out of Memory Errors

If n8n crashes or becomes unresponsive:

Check current limits:

docker service inspect n8n_n8n --format '{{json .Spec.TaskTemplate.Resources}}'

Recommended settings:

resources:
  limits:
    memory: 2G      # Increased from 1G
    cpus: '1.0'     # Increased from 0.5
  reservations:
    memory: 256M
    cpus: '0.1'

---

LM Studio Connection Issues

Problem

Workflows fail to connect to LM Studio at http://lm-studio:1234

Diagnostics

# Check if extra_hosts is configured
docker service inspect n8n_n8n | grep -A 5 ExtraHosts

# Test from n8n container
docker exec $(docker ps -q -f name=n8n) curl http://lm-studio:1234/v1/models

# Test direct connection
curl http://192.168.1.81:1234/v1/models

Solution

Ensure extra_hosts is configured in n8n-stack.yml:

extra_hosts:
  - "lm-studio:192.168.1.81"
  - "fedora:192.168.1.81"

---

Deployment

Apply Configuration Changes

# Update the stack
docker stack deploy -c /workspace/homelab/services/swarm/stacks/n8n-stack.yml n8n

# Watch service update
docker service ps n8n_n8n --no-trunc

# Check logs
docker service logs n8n_n8n --tail 50 --follow

Verify Health

# Check service status
docker service ls | grep n8n

# Test health endpoint
curl https://n8n.sj98.duckdns.org/healthz

# Check Traefik routing
docker service logs traefik_traefik --tail 20 | grep n8n

---

Common Workflow Issues

Webhook Not Triggering

1. Ensure workflow is active (toggle in UI)
2. Check webhook URL format: https://n8n.sj98.duckdns.org/webhook/<webhook-id>
3. Verify Traefik routing in logs
4. Test with curl:

   curl -X POST https://n8n.sj98.duckdns.org/webhook/health-check
   

Execute Command Node Fails

Ensure Docker socket is mounted:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

AI Node Timeout

Increase timeout in HTTP Request node options:

{
  "timeout": 30000  // 30 seconds
}

---

Monitoring

Check n8n Metrics

If N8N_METRICS=true is set:

curl http://localhost:5678/metrics

View Execution History

1. Open n8n UI
2. Go to "Executions"
3. Filter by "Failed" to see errors
4. Click execution to see detailed logs

Resource Usage

# Container stats
docker stats $(docker ps -q -f name=n8n)

# Service resource usage
docker service ps n8n_n8n