Avoiding Common Configuration Pitfalls in n8n

I run n8n a lot in my homelab and on client systems. I wrote this to cut straight to the faults I see most. Read it for symptoms, diagnostics, exact log lines, commands to run, root causes and step‑by‑step fixes. This focuses on n8n configuration pitfalls, setup issues and practical n8n troubleshooting.

What you see

Common error messages

• “Error: connect ECONNREFUSED 127.0.0.1:5432” — database connection refused.
• “SQLITE_BUSY: database is locked” — SQLite contention.
• “Request failed with status code 401” or “Invalid credentials for node ‘X'” — credential or token problems.
• “Workflow execution failed: TypeError: Cannot read property ‘json’ of undefined” — node input missing.
• “Webhook failed: 404 Not Found” — wrong external URL or proxy misconfig.

Unexpected behaviour in workflows

• Triggers not firing after deploy.
• Nodes returning empty outputs intermittently.
• Workflows pausing or queueing for no obvious reason.

Issues while connecting nodes

• API nodes failing with 401/403 despite correct tokens.
• SMTP/IMAP connections dropping with “TLS handshake failed”.
• Third‑party services rate limiting requests, causing partial runs.

I give the exact log lines above. Keep them handy. They point to discrete problems, not vague system malaise.

Where it happens

Specific nodes causing trouble

• HTTP Request and Webhook nodes break when reverse proxy headers are wrong.
• Database nodes fail if credentials or hostnames are wrong.
• OAuth nodes for Google or Microsoft break when redirect URI or client secret differ from the app settings.

Environment-specific issues

• Docker and docker‑compose: env vars not applied because compose file was changed but container not recreated.
• Kubernetes: wrong service name or missing ingress annotations leads to external URL mismatches.
• Local installs: port collisions, permission problems and file ownership on ~/.n8n.

Configuration file discrepancies

• Environment variables drift from deployed values. Use printenv to check live settings.
• Different config sources: systemd service, docker-compose, and GUI credentials can disagree.
• Reverse proxy config missing X‑Forwarded headers, so webhook URLs built by n8n are internal-only.

Pinpoint the area first. A database error stays in DB logs. A webhook error shows in proxy logs. Match the symptom to one of the three buckets above.

Find the cause

Diagnostic commands to run

• Inspect container logs:
  • docker logs -f n8n
  • docker-compose logs n8n –tail 200
• On Kubernetes:
  • kubectl logs -l app=n8n –tail=200
  • kubectl describe pod
• Check environment variables:
  • docker exec -it n8n printenv | grep -i n8n
  • env | grep -i n8n
• Test HTTP endpoints:
  • curl -I http://localhost:5678/ (expected: 200 or 301)
  • curl -I https:// (expected: 200)
• Test DB connectivity:
  • psql -h -U -d -c ‘\dt’ (expected: list of tables)
  • sqlite3 ~/.n8n/database.sqlite ‘PRAGMA integrity_check;’ (expected: OK)

Expected vs actual

• Expected: curl returns 200. Actual: 502 Bad Gateway. Root cause: reverse proxy misconfiguration.
• Expected: psql lists tables. Actual: psql: could not connect to server: Connection refused. Root cause: wrong DB host or firewall.
• Expected: workflow trigger recorded in n8n UI. Actual: no execution found. Root cause: webhook URL differs between n8n and proxy.

Checking logs for detailed errors

• Look for exact lines such as:
  • “Error: connect ECONNREFUSED 127.0.0.1:5432”
  • “SQLITE_BUSY: database is locked”
  • “Error: Request failed with status code 401”
• Grep for ERROR or WARN in the n8n logs:
  • docker logs n8n 2>&1 | grep -E ‘ERROR|WARN’ –color=never

Match the exact line to the failing component. That identifies the root cause quickly.

Fix

Step-by-step remediation

1. Backup first. Stop n8n and copy the database.
   • docker-compose down
   • cp ~/.n8n/database.sqlite ~/.n8n/database.sqlite.bak
2. Fix the database problem.
   • For SQLITE_BUSY: reduce concurrency or migrate to Postgres. SQLite locks on concurrent writes.
   • For Postgres errors: test with psql, then correct host, port or credentials in the environment.
3. Fix reverse proxy and webhook URL.
   • In nginx, add:
     • proxysetheader Host $host;
     • proxysetheader X-Forwarded-Proto $scheme;
     • proxysetheader X-Forwarded-For $remote_addr;
   • Check that the external webhook URL matches n8n’s idea of its base URL.
4. Correct credentials in n8n.
   • Re-enter API keys in the credentials manager.
   • If using exported credential JSON, import it again and confirm names match nodes.
5. Restart and monitor logs during restart.
   • docker-compose up -d
   • docker logs -f n8n

Common fixes for frequent issues

• Database contention: move from SQLite to Postgres for concurrent workloads.
• Webhook 404: set correct external URL and pass X‑Forwarded headers.
• 401/403 on API nodes: reissue tokens, check token scopes, and confirm redirect URIs for OAuth apps.
• TLS failures: check certificate chain on proxy and that n8n has plaintext or TLS as expected.

Testing configurations after changes

• Trigger a minimal workflow that exercises the failing node.
• Use curl to call webhook endpoints and compare response codes.
• Re-run the same request that failed previously and watch logs for the exact previous error line. If it does not appear, the fix likely worked.

List the root cause with remediation next to it; do the change, then test. That closes the loop.

Check it’s fixed

Verifying successful execution

• Trigger the workflow and expect:
  • UI shows execution with success status.
  • Logs have no ERROR lines for that run.
  • curl -I returns 200.
• For DB fixes, run a quick query:
  • psql -c ‘SELECT count(*) FROM execution_entity;’ (expected: increases after runs)

Monitoring for recurring problems

• Tail the logs for the next 24 hours:
  • docker logs -f n8n | tee n8n-log.txt
• Add a simple synthetic check:
  • cron job or Prometheus probe that curls the webhook and alerts on non-200.
• Check for repeated error lines:
  • grep -c ‘SQLITE_BUSY’ n8n-log.txt

Community resources for ongoing support

• Search the n8n forum and Reddit r/n8n for similar errors. Many threads include exact log lines and configuration snippets.
• Use official docs for node-specific credential requirements. They list required fields and typical causes of 401s.

Final checks and takeaways

• If an exact error line appeared before, reproduce the same request after the fix and confirm that line is gone from logs. That is concrete verification.
• For high concurrency use Postgres rather than SQLite.
• For webhooks behind a proxy, check X‑Forwarded headers and the external base URL.
• Keep a short checklist: backup DB, test DB, fix env vars, restart, retest webhook, watch logs.

Follow the steps above. They move you from symptom to diagnosis to a tested fix.