Deployment

How to Fix 502 Bad Gateway in Node.js and Nginx

A practical troubleshooting guide for 502 Bad Gateway errors in Node.js and Nginx with PM2 checks, proxy fixes, and log-first debugging.

April 20, 2026•ShortIQ Editorial Team

What a 502 Bad Gateway Usually Means

A 502 Bad Gateway error usually means Nginx is up, but it cannot successfully talk to the upstream application. In a Node.js deployment, that upstream app is often an Express server or a Next.js production server running behind PM2.

This is important because it tells you where to start. A 502 is usually not a frontend problem. It is usually a process problem, a port problem, or a proxy configuration problem.

Check Whether the App Is Actually Running

The first check should always be the process manager. If PM2 is not running the app correctly, Nginx has nothing healthy to proxy to.

bash

pm2 list
pm2 logs my-app
pm2 restart my-app

If PM2 shows the app as errored, fix that before touching Nginx
Look for startup exceptions, missing env values, or database errors

Verify the Local App Port

A very common cause of 502 is simple mismatch: Nginx is proxying to one port, while the Node.js app is listening on another. Confirm the port from both sides instead of assuming they match.

bash

ss -tulpn | grep 3000
curl -I http://127.0.0.1:3000

nginx

location / {
    proxy_pass http://127.0.0.1:3000;
}

Test and Read Nginx Properly

If the app is healthy but the public site still returns 502, move to the Nginx layer. Syntax-test the config first, then inspect the error log. Do not guess at proxy problems when the log can usually tell you exactly what failed.

bash

sudo nginx -t
sudo systemctl status nginx
sudo tail -f /var/log/nginx/error.log

Common Root Causes

If the Node app crashes immediately after startup, PM2 logs usually show the real reason. Missing environment variables, database connection failures, wrong working directory, and bad build output are all common causes. If the app stays up but Nginx still fails, the proxy target, headers, or firewall rules are more likely to blame.

In practice, the most common root causes are: the app is not running, the app is on the wrong port, Nginx has the wrong proxy_pass, or the app starts but crashes under load or on boot.

PM2 process not running
Wrong upstream port
Bad proxy_pass value
App crash from env or database issue
Firewall or binding issue

A Fast Recovery Workflow

When you need to recover quickly, use the same sequence every time: check PM2, check the app port, test Nginx, then read logs. This avoids random debugging and usually gets you to the real cause faster.

bash

pm2 list
pm2 logs my-app
ss -tulpn | grep 3000
curl -I http://127.0.0.1:3000
sudo nginx -t
sudo tail -f /var/log/nginx/error.log

FAQ

What causes 502 Bad Gateway in Node.js and Nginx?

Usually Nginx cannot reach the upstream Node.js app because the process is down, the port is wrong, or the proxy configuration is incorrect.

Should I check Nginx or PM2 first?

Check PM2 first. If the app is not healthy, Nginx cannot proxy to it successfully.

Can a missing environment variable cause 502?

Yes. If the app crashes on startup because of a missing env value, Nginx may surface that failure as a 502.

How do I confirm the correct upstream port?

Use ss or curl locally against 127.0.0.1 and compare the result with the proxy_pass value in your Nginx config.

What log should I read for 502 errors?

Start with PM2 logs for the app and then read /var/log/nginx/error.log for the proxy-side failure details.

Related free tools

If you want to turn this topic into action, use one of ShortIQ's free tools for campaign planning, UTM structure, or QR distribution.

Continue Reading

Explore more guides on link shortener SaaS strategy, Bitly alternatives, and white label link management.