If you've ever tried to troubleshoot n8n errors after a fresh install, you already know the difficulties. Everything works fine during setup, then things go wrong after you push to production. This guide covers the most common n8n errors, including webhook URLs not firing, 502 and 504 errors behind Nginx or Caddy, workflows timing out, and environment variables that silently disappear after a Docker Compose migration.
You need n8n running in Docker on a Linux VPS, a domain with DNS pointed to your server, and either Nginx or Caddy as a reverse proxy. If you haven't set it up, you can check this guide on Installing n8n on a VPS.
1. n8n Webhook URLs Not Firing
This is the most common issue for self-hosted n8n. The symptom is that your webhook works perfectly in test mode when you click Listen for test event, but in production, it returns a 404 or never triggers.
When n8n runs behind a reverse proxy, it builds the webhook URL internally by combining:
N8N_PROTOCOL, N8N_HOST, and N8N_PORT
Since n8n listens on port 5678 internally, the generated URL looks like:
http://your-server:5678/webhook/…
This is wrong for external callers who reach your server on port 443. The fix is to override the webhook URL manually.
Fix 1: Set WEBHOOK_URL in Docker Compose
To troubleshoot n8n errors for Webhook, open your docker-compose.yml file:
nano ~/n8n/docker-compose.yml
Add or update the environment section:
1services:2 n8n:3 image: docker.n8n.io/n8nio/n8n4 environment:5 - WEBHOOK_URL=https://your-domain.com/6 - N8N_PROXY_HOPS=17 - N8N_HOST=your-domain.com8 - N8N_PROTOCOL=https9 - N8N_PORT=5678
docker compose down && docker compose up -d
1[+] Running 1/12 ✔ Container n8n Started
Fix 2: Verify the Webhook URL Is Correct Inside the Container
After restarting, you must check that the environment variables are loaded correctly:
docker exec -it n8n printenv | grep -i webhook
WEBHOOK_URL=https://your-domain.com/
If you see localhost:5678 here, the variable did not load. Check for typos in your docker-compose.yml or ensure your .env file is referenced properly.
Fix 3: Test the Production Webhook with curl
N8n has two webhook URLs, one for testing and one for production. Make sure you're using the Production URL without the word test in it:
curl -X POST https://your-domain.com/webhook/your-path \ -H "Content-Type: application/json" \ -d '{"test": "hello"}'
1{2 "status": "success"3}
If you get a 404 error, double-check that:
- The workflow is active, not just saved.
- You are using the production URL, not the test URL.
- The workflow has been saved at least once. Unsaved workflows do not register webhooks.
When n8n sits behind a reverse proxy, it needs to know how many proxy layers are in front of it so it can trust the X-Forwarded-* headers:
1environment:2 - N8N_PROXY_HOPS=1
Also, this is documented in the official n8n docs as a required step when using any reverse proxy.
2. How to Troubleshoot n8n Errors Behind Nginx (502 / 504)
502 Bad Gateway and 504 Gateway Timeout are the most common errors when you troubleshoot n8n errors in production. They almost always come from one of three causes:
- Nginx's default read timeout is too low.
- Buffer limits on large webhook payloads.
- WebSocket support is missing for the n8n editor.
Check if your error happens at a consistent time, for example, always around 60 seconds. That is a clear sign of a proxy timeout, not an application bug:
docker logs -f n8n sudo tail -f /var/log/nginx/error.log
Full Working Nginx Config for n8n
Create or replace your Nginx site config:
sudo nano /etc/nginx/sites-available/n8n
Paste the following complete configuration:
map $http_upgrade $connection_upgrade { default upgrade; '' close;} server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; location / { proxy_pass http://localhost:5678/; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Port $server_port; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_read_timeout 3600s; proxy_send_timeout 3600s; proxy_connect_timeout 300s; proxy_buffering off; proxy_cache off; chunked_transfer_encoding off; client_max_body_size 50M; }} server { listen 80; server_name your-domain.com; return 301 https://$host$request_uri;}
sudo nginx -tsudo systemctl reload nginx
Key Settings:
| Setting |
Default |
Recommended |
Why |
| proxy_read_timeout |
60s |
3600s |
Long workflows exceed 60s easily |
| proxy_send_timeout |
60s |
3600s |
Prevents drops on large responses |
| client_max_body_size |
1M |
50M |
Large JSON payloads from webhooks |
| proxy_buffering |
on |
off |
Required for n8n's streaming output |
| proxy_http_version |
1.0 |
1.1 |
Required for WebSocket and keepalive |
If n8n is in the Same Docker Network as Nginx
Do not use localhost as the proxy target if both containers are on the same Docker network. Use the container name instead:
proxy_pass http://n8n:5678/;
And make sure both services share the same Docker network in docker-compose.yml:
1services:2 nginx:3 networks:4 - n8n_net5 n8n:6 networks:7 - n8n_net8 9networks:10 n8n_net:
3. Fix Caddy Reverse Proxy Errors in n8n
Caddy is simpler to configure than Nginx, but it still has some troubles when used with n8n. The most common issue is n8n generating webhook URLs with :5678 appended because Caddy is not forwarding the correct port headers.
Working Caddyfile for n8n
To troubleshoot n8n errors for the Caddy reverse proxy, adjust the file:
sudo nano /etc/caddy/Caddyfile
your-domain.com { reverse_proxy localhost:5678 { header_up X-Forwarded-Proto https header_up X-Forwarded-Port 443 header_up Host {host} flush_interval -1 }}
The flush_interval -1 line disables response buffering, which is important for n8n's real-time log streaming.
Reload Caddy:
sudo systemctl reload caddy
Test that the headers are passing correctly:
curl -I https://your-domain.com/webhook/test
Look for X-Forwarded-Proto: https in the response headers. If it's missing, the proxy headers are not being forwarded.
If n8n is in a Docker Container and Caddy is on the Host
your-domain.com { reverse_proxy localhost:5678 { header_up X-Forwarded-Proto https header_up X-Forwarded-Port 443 }}
If both are in Docker Compose, use the container name:
your-domain.com { reverse_proxy n8n:5678 { header_up X-Forwarded-Proto https header_up X-Forwarded-Port 443 }}
4. Fix Execution Timeouts on Long Workflows in n8n
When you troubleshoot n8n errors related to long workflows stopping mid-run, the culprit is usually one of two things:
- The n8n execution timeout environment variable.
- The reverse proxy is cutting the connection before n8n finishes.
N8n uses two separate environment variables for timeouts:
| Variable |
Default |
Description |
| EXECUTIONS_TIMEOUT |
-1 (disabled) |
Default timeout in seconds for all workflows |
| EXECUTIONS_TIMEOUT_MAX |
3600 |
Maximum time in seconds a user can set per workflow |
Important Note: EXECUTIONS_TIMEOUT values are in seconds, not milliseconds. Setting EXECUTIONS_TIMEOUT=3600 means 1 hour.
Set Execution Timeout in Docker Compose
1services:2 n8n:3 image: docker.n8n.io/n8nio/n8n4 environment:5 - EXECUTIONS_TIMEOUT=7200 6 - EXECUTIONS_TIMEOUT_MAX=14400
docker compose down && docker compose up -d
Verify the variables loaded:
docker exec -it n8n printenv | grep EXECUTIONS
1EXECUTIONS_TIMEOUT=72002EXECUTIONS_TIMEOUT_MAX=14400
Fix for Code Node Timeouts (Task Runner)
If you upgraded n8n to version 1.x or 2.x and your Code nodes now time out after 5 minutes, the new task runner system may be the cause.
Add this to your environment:
1environment:2 - N8N_RUNNERS_ENABLED=true3 - N8N_RUNNERS_TASK_TIMEOUT=600000
If the problem persists, you can disable the new runner system to fall back to the older method:
1environment:2 - N8N_RUNNERS_ENABLED=false
Check What Is Actually Timing Out
Run this to see what is happening when a workflow stops:
docker logs n8n --since 30m | grep -i "timeout|error|killed"
If you see no timeout-related log entries from n8n but the execution still stopped, the timeout is coming from your reverse proxy; go back to Section 2 and increase proxy_read_timeout.
5. Fix n8n Broken Environment Variables After Moving to Docker Compose
When you migrate n8n from a bare Docker run command to Docker Compose, environment variables often stop working, especially if you used an .env file incorrectly.
Step 1: Check if Your .env File Is in the Right Place
Docker Compose automatically reads a .env file only if it is in the same directory as your docker-compose.yml.
If the .env file is missing, create it:
cp .env.example .envnano .env
Step 2: Verify Docker Compose Picks Up the Variables
This command prints the fully resolved configuration. Search for your variable in the output:
docker compose config | grep WEBHOOK_URL
WEBHOOK_URL: https://your-domain.com/
If the variable is blank or missing, the .env file is not being loaded. Check for syntax errors, no spaces around =, no quotes unless necessary:
WEBHOOK_URL=https://your-domain.com/ WEBHOOK_URL = https://your-domain.com/
Step 3: Reference Variables Correctly in docker-compose.yml
There are two ways to pass variables. Use one, not both:
Method A. inline value, no .env file needed:
1environment:2 - WEBHOOK_URL=https://your-domain.com/3 - N8N_PROXY_HOPS=1
Method B. reference from .env file:
1environment:2 - WEBHOOK_URL=${WEBHOOK_URL}3 - N8N_PROXY_HOPS=${N8N_PROXY_HOPS}
WEBHOOK_URL=https://your-domain.com/N8N_PROXY_HOPS=1
Step 4: Force a Clean Restart
Docker Compose may cache old values. Do a full restart to make sure fresh variables are applied:
docker compose downdocker compose up -d
Verify all key variables inside the running container:
docker exec -it n8n printenv | grep -E "WEBHOOK|N8N_HOST|N8N_PROTOCOL|EXECUTIONS"
1WEBHOOK_URL=https://your-domain.com/2N8N_HOST=your-domain.com3N8N_PROTOCOL=https4EXECUTIONS_TIMEOUT=7200
Useful n8n Debug Commands Cheat Sheet
When you need to troubleshoot n8n errors quickly without reading through logs manually, these commands save time:
docker logs n8n --tail 100 docker logs -f n8n docker exec -it n8n printenv curl -v -X POST https://your-domain.com/webhook/your-path \ -H "Content-Type: application/json" \ -d '{"key":"value"}' curl -v http://localhost:5678/healthz sudo tail -50 /var/log/nginx/error.log sudo nginx -t sudo systemctl reload nginx sudo systemctl reload caddy docker network inspect bridge docker inspect n8n | grep -A 20 Networks
Running Complex or Scaled Workflows
If your n8n instance handles high-volume automations or long-running jobs, a single-container setup may not be enough. Queue mode lets you separate the main process from workers, so one slow workflow does not block others.
To troubleshoot n8n errors related to performance and scaling at the same time, read the n8n Queue Mode scaling guide, which covers Redis integration, worker configuration, and how to set EXECUTIONS_MODE to queue.
A reliable Linux VPS with consistent uptime is also important. If your server runs out of memory or restarts unexpectedly, all active executions are lost. For stable n8n hosting with enough RAM for Docker and a database, take a look at PerLod Linux VPS plans; they're a solid base for production automation setups.
Conclusion
Most n8n production issues depend on a few root causes, such as wrong WEBHOOK_URL, Nginx/Caddy timeouts that are too short, execution timeout variables set incorrectly, and .env files not loading properly. When you troubleshoot n8n errors, always start by checking your environment variables inside the container, then verify your reverse proxy logs, and finally test your webhook URL directly with curl.
For domain setup and SSL, a proper domain pointing to your VPS IP is required for HTTPS webhooks. You can easily register and manage domains at PerLod Domain Registration.
