Nginx doesn’t just break for fun. A 502 means the bridge is out. Whether you’re fighting Docker network aliases or Kubernetes readiness probes, here is how we fix the "Bad Gateway" once and for all.

It’s 2 a.m. Your Slack is blowing up with PagerDuty alerts, and your ingress is bleeding 502s. You’ve restarted the Nginx container three times. Nothing. Still that cold, grey "Bad Gateway" screen staring back at you.

Here’s the thing: Nginx is rarely the problem. It’s just the messenger. It tried to talk to your backend your Go service, your Python 3.15 app, or that Rust microservice and got a door slammed in its face.

I’ve spent 30 years in this game. I’ve seen 502s cost companies $50k in an hour of downtime. It’s usually not a "bug" in the code. It’s a failure in the plumbing.

The "Bridge is Out" Reality Check

In a containerized world, a 502 happens for three specific reasons. Don't look anywhere else until you’ve checked these:

1. The Backend is Dead: Your app container crashed or hasn't finished booting.
2. The Address is Wrong: Nginx is looking for localhost, but in Docker, "localhost" is the Nginx container itself, not your app.
3. The Connection Timed Out: Your app is alive but it’s struggling. It didn't respond fast enough, and Nginx gave up.

Docker: The Networking Trap

If you’re running Nginx and your app in docker-compose, the most common mistake is the proxy_pass directive.

What doesn't work:

proxy_pass http://localhost:8000;

What actually works:

Use the service name defined in your YAML. If your app service is named api-backend, your config must reflect that.

War Story: I once saw a team spend six hours debugging a 502 because they were using IP addresses in their Nginx config. The containers restarted, the IPs shifted, and the "bridge" pointed to nowhere. We fixed it by using Docker Network Aliases. Use names, not numbers.

Kubernetes: The Readiness Probe Nightmare

In Kubernetes, 502s are often "Ghost Errors." One minute it works, the next it’s gone. This is usually your Readiness Probe lying to the cluster.

If your pod says it’s "Ready" but the app hasn't fully initialized its database connection or loaded its cache, Kubernetes starts sending traffic. Nginx (the Ingress Controller) tries to route a request to that pod, the pod rejects it, and boom 502.

The Fix Checklist:

• Align your probes: Ensure your readinessProbe actually checks a route that requires the DB to be up.
• Resources: Check the OOMKiller. If your pod is hitting its memory limit, K8s kills it. While it’s restarting, Nginx has nowhere to send traffic.
• Service Selectors: Double-check your labels. If your Service selector doesn't perfectly match your Pod labels, the Service has zero endpoints. Nginx can’t talk to a vacuum.

The "Silent Killer" Configs

Sometimes the app is fine, but Nginx is too impatient. If you’re running heavy data processing (like a Polars join or a complex Rust calc), the default 60-second timeout isn't enough.

Add these to your location block. Don't be shy with the numbers if your backend is doing heavy lifting

The Final Verdict

Stop treating Nginx like a black box. If you see a 502, stop looking at the Nginx logs and start looking at the connectivity. Use curl from inside the Nginx container to see if it can even reach the backend.

If curl api-backend:8000 fails, your Nginx config is fine your network is broken. Fix the plumbing, and the gateway will open.