SteadyNode

Nginx / Envoy · HTTP 502

Nginx 502: Upstream Connection Refused

Fix Nginx 502 when connect() to an upstream is refused. Verify the process, socket or port, container network, and upstream configuration.

Origin / Network Firewall

Decode a CDN or gateway error

Paste a captured HTTP response or enter a status and headers. Only the status and response headers are sent; common credential headers are filtered first.

Supports raw headers, full HTTP responses, JSON with status/statusCode and headers, cURL -v/-i response output, and HAR exports. HAR selects a server error first. cURL commands are never executed; request headers, response bodies, and common credential headers are excluded.

Diagnostic report

Error code / name

NGINX-502

Fault domain

Origin / Network Firewall

Why it happened

Nginx could not open a TCP connection to its configured upstream. The exact error `connect() failed (111: Connection refused) while connecting to upstream` usually means no process is listening at that address and port, or a local policy rejected the connection.

Actionable fixes

  1. Check Nginx error logs for the upstream address and compare it with the application's actual listen port.
  2. Confirm the upstream process is healthy and reachable from the Nginx host or container network.
  3. Use service DNS names between containers; do not point one container at localhost for another container.

Why this error happened

Nginx could not open a TCP connection to its configured upstream. The exact error `connect() failed (111: Connection refused) while connecting to upstream` usually means no process is listening at that address and port, or a local policy rejected the connection.

Actionable fixes

  1. Check Nginx error logs for the upstream address and compare it with the application's actual listen port.
  2. Confirm the upstream process is healthy and reachable from the Nginx host or container network.
  3. Use service DNS names between containers; do not point one container at localhost for another container.

Network failure point

Client -> Nginx -> TCP connect to 127.0.0.1:3000 -> RST / refused -> X 502

Verify origin directly via CLI

curl -sS -v -I --connect-timeout 3 --max-time 10 http://127.0.0.1:3000/health

Configuration fix

nginx.confnginx
upstream app {
    server 127.0.0.1:3000;
}
server {
    location / {
        proxy_pass http://app;
    }
}

Catch this failure before it becomes an outage

SteadyNode's Upstream Translator recognizes Nginx gateway signatures and explains the likely connection boundary, while scheduled checks detect the public impact.

No credit card required.

Start for free

Frequently asked questions

What does Nginx connect() failed (111: Connection refused) mean?

Nginx reached the host but the upstream TCP connection was rejected, usually because no process listens at the configured address and port.

Should I use localhost for an upstream in Docker?

Only when Nginx and the application share the same network namespace. In separate containers, use the application's service name and container port.

More CDN and gateway error guides

Cloudflare

Vercel and Netlify

AWS CloudFront and ALB

Fastly

Heroku and Render

Nginx and Envoy