“Bad Gateway” (HTTP 502) on your n8n install means your reverse proxy — usually Nginx — is running, but it cannot reach n8n itself. The fix is a short diagnostic checklist: confirm n8n is actually running, check the logs, verify the port and domain settings, then restart cleanly.
Quick mental model of the problem
Traffic flows like this: visitor → Nginx (ports 80/443) → n8n (usually port 5678 on localhost). A 502 means the first hop works and the second hop fails. So the fault is almost always one of these: n8n is not running, n8n listens on a different port than Nginx expects, n8n crashed from lack of memory, or its domain settings are wrong.
Step 1 — Is n8n actually running?
For Docker installs:
docker ps | grep n8nIf no container is listed, n8n is down — skip to the restart step after checking the logs. For npm/PM2 installs:
pm2 listor, for systemd:
systemctl status n8nStep 2 — Read the logs
The logs usually name the cause directly:
docker logs --tail 100 n8nLook for: database errors (“SQLITE” corruption or migration failures), “port already in use” (two n8n copies fighting), out-of-memory kills, or crashes during startup after an update. For PM2: pm2 logs n8n –lines 100.
Step 3 — Check the port match
Nginx must forward to the port n8n actually listens on. Check what is listening:
ss -tulpn | grep 5678Then check your Nginx site config (/etc/nginx/sites-available/) — the proxy_pass line should point at the same port, for example proxy_pass http://localhost:5678;. A mismatch here is one of the most common causes after a reinstall or config edit. If you changed them, run nginx -t && systemctl reload nginx.
Step 4 — Verify the domain environment variables
n8n needs to know its public address. In your Docker Compose file or docker run command, confirm:
N8N_HOST=n8n.yourdomain.com
WEBHOOK_URL=https://n8n.yourdomain.com/Wrong values here do not always cause a 502 on the main UI, but they reliably break webhooks and OAuth callbacks — and a protocol mismatch (http vs https) can cause redirect loops that look like gateway errors. After editing, recreate the container (docker compose up -d).
Step 5 — Rule out resource exhaustion
Small VPS plans run out of RAM, and Linux kills n8n to survive:
free -m
df -h
dmesg | grep -i "killed process" | tailIf memory is the problem, you will see OOM-killer entries naming node. Short-term fix: restart n8n and reduce concurrent workflow executions. Long-term fix: upgrade the VPS plan or move the database to SQLite-light usage. A full disk (100% on df -h) also stops n8n cold — clear old Docker images and logs with docker system prune (carefully) and log rotation.
Step 6 — Restart cleanly
cd /path/to/your/n8n
docker compose down
docker compose up -d
docker compose logs -f n8nWatch the startup logs until n8n reports it is ready, then reload the page. For npm installs: pm2 restart n8n.
Preventing the next 502
- Set restart: unless-stopped on the n8n container so it recovers from crashes and reboots by itself.
- Add a Docker healthcheck so a half-started n8n gets restarted automatically.
- Monitor the VPS: a simple uptime check that alerts you is worth more than any log dashboard.
- Do not update n8n right before you need it — updates are the second most common trigger after memory.
- Keep at least 20% disk and some RAM headroom; n8n with many executions is hungrier than it looks.
When the 502 is intermittent
A 502 that comes and goes is harder than a permanent one, but the suspects narrow quickly. Intermittent gateway errors on a small VPS almost always mean one of three things. First, memory pressure under load: n8n is fine at idle but gets OOM-killed when several workflows execute at once. Correlate the 502 timestamps with dmesg OOM entries and your workflow schedule — if they line up, stagger heavy executions or add RAM. Second, slow startups after a restart: right after docker compose up -d, n8n needs 30–60 seconds to initialize while Nginx already forwards traffic. A brief 502 window after deploys is normal; a healthcheck with a start period eliminates false alarms. Third, database locks on SQLite: the default SQLite database serializes writes, so many concurrent executions can stall and time out behind the proxy. If you consistently run parallel workloads, migrating n8n to PostgreSQL (documented in n8n’s own hosting guides) removes this ceiling.
Reading Nginx’s side of the story
So far we have interrogated n8n; Nginx keeps its own evidence in /var/log/nginx/error.log. Two entries matter most. “connect() failed (111: Connection refused) while connecting to upstream” means nothing listens on the proxied port — n8n is down or on a different port. “upstream timed out” means n8n accepted the connection but never answered in time — it is overloaded, locked, or stuck in startup. The distinction tells you whether to restart the container or investigate performance. Also check access.log around the failure time: a 502 for every URL points at n8n being down, while 502s only on /webhook/… paths point at webhook configuration.
Frequently asked questions
I get a 502 right after updating n8n. What happened?
Most likely a breaking change or a failed database migration. Read the container logs — migration errors are explicit. If you cannot resolve it, roll back to the previous image version (see our n8n update guide) and check the release notes before trying again.
The n8n UI loads but webhooks return 502. Why?
The UI and webhooks can fail independently. This pattern usually points at WEBHOOK_URL being wrong or unreachable. Set it to the exact public HTTPS URL and recreate the container.
n8n works on the VPS IP and port, but not on my domain. What is wrong?
That isolates the fault to Nginx or DNS: the proxy config, the domain’s A record, or the SSL certificate. Check nginx -t, confirm the A record points at the VPS, and re-run certbot if the certificate expired.
How do I tell whether the problem is Nginx or n8n?
Fetch n8n directly, bypassing Nginx: curl -I http://localhost:5678 on the server. If that answers, n8n is fine and Nginx is misconfigured. If it fails, n8n itself is the problem — work through the steps above.