502 Bad Gateway Error with NGINX Reverse Proxy for Node.js App – How to Debug?

Projects NGINX
, ,
1

Hi NGINX Community,

I’m running into a 502 Bad Gateway error when using NGINX as a reverse proxy for my Node.js application. The setup works intermittently, but the error appears randomly, breaking my app’s frontend. I’m new to NGINX and need help debugging this.

Details:

  • Environment: Ubuntu 22.04, NGINX 1.26.0 (latest, July 2025), Node.js 20.x running on port 3000.
  • Setup: NGINX as reverse proxy, forwarding requests from example.com to localhost:3000. Using default SSL (Let’s Encrypt).
  • Config:
server {
    listen 80;
    server_name example.com;
    return 301 https://$server_name$request_uri;
}
server {
    listen 443 ssl;
    server_name example.com;
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
  • Issue: 502 Bad Gateway errors occur randomly (e.g., after 5–10 requests). Node.js app is running (confirmed via curl localhost:3000).
  • Logs: NGINX error log shows:
2025/07/03 14:32:10 [error] 1234#1234: *5 connect() failed (111: Connection refused) while connecting to upstream, client: 192.168.1.100, server: example.com, upstream: "http://127.0.0.1:3000/"
  • Steps Tried:
    1. Restarted NGINX (sudo systemctl restart nginx) and Node.js app.
    2. Verified Node.js is listening on localhost:3000 (works via direct curl).
    3. Checked firewall (ufw allow 80,443) and permissions on SSL certs.
    4. Increased proxy_timeout to 30s in NGINX config—no change.
    5. Read NGINX docs on reverse proxy but couldn’t pinpoint the issue.
  • Expected: Stable proxying to Node.js app without 502 errors.
  • Actual: Random 502 Bad Gateway errors, connection refused in logs.

Questions:

  1. Is my NGINX config missing key directives for stable proxying to Node.js?
  2. Could the “Connection refused” error indicate a Node.js issue, and how do I debug it?
  3. Any best practices for NGINX reverse proxy settings (e.g., buffers, timeouts)?
  4. Should I check specific server resources (e.g., memory, CPU) affecting upstream?

I’ve reviewed the Community Guidelines and want to ensure my config is solid. Any debugging tips or config tweaks would be greatly appreciated!

1 Like
2

According to the logs you provided, it is obvious that the problem occurs in the upstream service, that is, your node.js. There is no problem with nginx (the only possible problem is that it does not provide upstream long connection support). node.js (127.0.0.1:3000) rejected the TCP connection. I believe you can use tools such as curl to bypass nginx to request this endpoint and reproduce the same problem. I am not sure about the debugging method of the node.js server. You may need to seek help from other people who are familiar with node.js.

1 Like
3

Since Node.js is rejecting the connections from NGINX, what do your application logs show when you see this failure?

1 Like