Avoiding Common Configuration Pitfalls in n8n

I run n8n a lot in my homelab and on client systems. These are the faults I keep seeing: the symptoms, the logs that point at them, and the fixes that actually help.

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.

Keep the exact log lines handy. They point to separate faults, not vague system noise.

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 the compose file changed but the container was 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.

Start by pinning the area down. Database errors sit in DB logs. Webhook errors show up 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 <pod-name>

• 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://<external-webhook-url>  # expected: 200

• Test DB connectivity:

psql -h <host> -U <user> -d <db> -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 gets you to 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:

proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header 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 watch the 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 the 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 the certificate chain on the proxy and that n8n is using 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.
• Run the same request that failed before and watch for the exact previous error line. If it does not appear, the fix likely worked.

List the root cause with the fix next to it; make 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 <webhook> returns 200.

For DB fixes, run a quick query:

psql -c 'SELECT count(*) FROM execution_entity;'

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 the usual causes of 401s.

Final checks and takeaways

• If an exact error line appeared before, run the same request after the fix and check that line is gone from the logs. That is the clean test.
• 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.