How to fix "502 Bad Gateway" from nginx

Your site is there one minute, then nginx shows a cold white page saying “502 Bad Gateway” and gives you almost nothing to work with.

Short version: “502 Bad Gateway” from nginx usually means nginx is reachable, but the app behind it is not answering correctly. The nginx 502 bad gateway fix is to find which link broke: the app process, the port or socket nginx sends traffic to, Docker networking, server resources, or a timeout.

What does “502 Bad Gateway” from nginx mean?

nginx is often the front desk for your website. A visitor asks for your site, nginx receives the request, then passes it to the real worker behind the desk: your app, WordPress, Node.js service, PHP-FPM, Python app, or a container.

A “502 Bad Gateway” means the front desk was open, but the worker behind it gave no usable answer.

That is different from a domain problem. If the domain points nowhere, the request may never reach your server. That is also different from a browser security warning, which is usually about HTTPS certificates. If you are unsure whether traffic reaches the server at all, start with the three-layer check in why your website is not loading.

With nginx, the important detail is this: nginx is usually not the broken application. It is the messenger telling you the application behind it failed to respond.

Why does nginx return 502?

Most nginx 502 errors come from one of a few plain causes.

The app may be stopped. nginx is knocking on a door, but nobody is inside. This happens after a crash, a failed deploy, a server restart, or a service that was never started.

nginx may be pointing to the wrong place. For example, the app listens on one port, while nginx tries another. Think of it like writing the right street but the wrong apartment number.

The app may be too slow or overloaded. nginx waits for an answer, gives up, and returns “502 Bad Gateway.” If this appears during traffic spikes, imports, image processing, backups, or deploys, the server may be running out of CPU, memory, or disk breathing room. That overlaps with the symptoms in why your server is slow.

Docker can add another layer. If nginx runs outside a container and your app runs inside one, the name, port, and network path all need to line up. Docker is useful, but it changes where “localhost” is. For a beginner-friendly mental model, see Docker on a server for beginners.

How do you find the real nginx 502 Bad Gateway fix?

Do not start by editing random nginx files. A 502 is a broken chain, so walk the chain from the visitor inward.

First, confirm nginx itself is alive. If nginx is serving the error page, it is probably running. That means your attention should move behind nginx, toward the upstream app. “Upstream” is nginx’s word for the service it sends requests to.

Next, check whether the app is running. If your app has its own process manager, container, or runtime, look there. A crashed app often leaves a clear message: missing environment variable, database connection refused, permission denied, port already in use, or a dependency that failed to start.

Then check the address nginx uses to reach the app. The common mistake is a mismatch between the app’s actual listening port and the port nginx expects. Another common mistake is using “localhost” from the wrong place, especially with containers. In Docker, “localhost” inside one container usually means that same container, not another one.

Finally, check timing and capacity. If the app starts but takes too long to answer, nginx may return 502 while the app is still busy. That points to slow database queries, heavy background jobs, low memory, or an app that needs more time than nginx allows.

Is it nginx, your app, Docker, or the server?

A useful way to think about the nginx 502 bad gateway fix is to ask which layer last worked.

If nginx logs say the connection was refused, the app probably is not listening where nginx expects it. If they say the upstream timed out, the app may be alive but too slow. If the app logs show a crash at the same time as the 502, the app is the first place to fix. If Docker says a container keeps restarting, nginx is only reporting that churn.

If the problem appears only after a deploy, suspect a changed port, a missing secret, a broken build, or a migration that failed. If it appears only under load, suspect memory pressure, CPU saturation, or database slowness. If it appears after moving domains or adding another site, suspect that one nginx site block is sending traffic to the wrong app.

This is why “restart nginx” sometimes appears to work but does not really fix the issue. It can clear a stuck moment, but it does not repair a crashed app, a wrong upstream address, or a server that keeps running out of memory.

The shortcut

Server Manager helps by keeping the moving parts visible: which site points to which app, which port belongs to which project, and whether the service behind nginx is actually running. That spares you the usual 502 guessing game where nginx looks guilty, but the real cause is a stopped app, a wrong internal port, or one project accidentally pointing at another.

The real benefit is that the setup stays legible months later. When you return to a site after a quiet stretch, you are not trying to remember which container, domain, certificate, and app process belonged together.

For this specific error, that means fewer blind restarts and fewer late-night edits to files you barely remember. You can reason from the site to the app behind it, instead of treating “502 Bad Gateway” as a mystery wall.

FAQ

Does “502 Bad Gateway” mean nginx is down? Usually no. If nginx shows the error page, nginx is running. The problem is commonly the app or service behind it.

Can DNS cause an nginx 502 error? Not usually. DNS decides whether visitors reach your server. A 502 usually happens after nginx has already received the request.

Is a 502 the same as a 504? No. A 502 means nginx got a bad or unusable response from the upstream service. A 504 usually means nginx waited too long and timed out.

Can a bad HTTPS certificate cause 502 Bad Gateway? Usually it causes a browser certificate warning, not a 502. HTTPS problems are a different layer; see free HTTPS on your server if certificates are the issue.

What does “fixed” look like?

You know the fix is real when nginx can consistently reach the app behind it, not just after one lucky restart.

The site loads, the app logs stop showing crashes, nginx stops reporting upstream failures, and the same request works more than once. Better yet, you understand what broke: the app was stopped, the port was wrong, Docker networking was misread, or the server was out of room.

That understanding is the win. The next time “502 Bad Gateway” appears, it is not a blank wall. It is a signpost telling you where to look next.