Why Does Nginx 502 Bad Gateway Occur?

What does 502 Bad Gateway mean?

A 502 Bad Gateway response usually means that Nginx could not obtain a valid response from the application or service behind it.

It does not necessarily mean Nginx itself is down. If Nginx can display a 502 page, it has generally accepted the request but failed to communicate correctly with the backend service.

User → Nginx → Backend application → Database or other services

The backend application is unavailable

Nginx forwards requests to an IP address, port or Unix socket. If the application has stopped, is restarting continuously or is not listening on the expected port, Nginx cannot establish a valid connection.

Restarting Nginx alone rarely provides a permanent solution. The reason the upstream application became unavailable must be identified.

• Application did not start after deployment
• Container is continuously restarting
• Service is listening on the wrong port
• Process was terminated because of memory pressure
• Application is running but not ready to receive traffic

Incorrect proxy_pass address or port

Nginx cannot reach the backend if the configured address, port or protocol is incorrect. The application port may have changed while the Nginx configuration remained unchanged.

Connecting with HTTPS to a service that expects HTTP, or HTTP to a service that expects HTTPS, can also prevent Nginx from receiving a valid response.

Docker network or service-name problems

When Nginx and the application run in separate containers, localhost refers to the Nginx container itself—not the backend application.

A container being marked Up is not sufficient. Connectivity must be verified from the network context in which Nginx is running.

• Containers are not attached to the same network
• Compose service name has changed
• Backend container failed to start
• Application listens only on 127.0.0.1
• Nginx is using an outdated IP address

The backend closes the connection early

Nginx may connect to the backend, but the application can close the connection before returning a valid HTTP response. The error log may contain upstream prematurely closed connection.

This message only confirms that the connection ended unexpectedly. The actual root cause is usually found in the application logs from the same time window.

• Unhandled application exception
• Worker process crash
• Memory exhaustion
• Application-level timeout
• Database connection problem
• Process termination during deployment

Unix socket permissions

Nginx can communicate with PHP-FPM, Gunicorn and similar services through a Unix socket. Even when the socket exists, the Nginx worker user may not have permission to access it.

Granting broad write permissions without understanding ownership can hide the symptom temporarily while introducing a serious security risk.

• Socket owner and group
• File and parent-directory permissions
• Nginx worker user
• Application socket creation settings

Resource exhaustion

A backend can appear to be running while CPU, memory, disk or connection limits prevent it from serving requests.

Increasing timeout values in this situation can make users wait longer without addressing the actual bottleneck.

• OOM events and memory pressure
• Full disk or exhausted inodes
• Sustained CPU saturation
• Exhausted database connection pool
• Insufficient worker capacity
• File descriptor limits

The difference between 502 and 504

502 Bad Gateway indicates that Nginx did not receive a valid response from the upstream. 504 Gateway Timeout indicates that the upstream did not respond within the expected time.

The HTTP status alone is not enough to determine the root cause. Nginx logs, application logs and the incident timeline must be evaluated together.

Safe initial checks

Before changing a production environment, establish the scope of the failure, when it began and whether it correlates with a recent change.

• Does the error affect every URL or one endpoint?
• Is the backend listening on the expected address and port?
• Can Nginx reach the backend from its own environment?
• Did the error begin after a deployment?
• What do Nginx and application logs show in the same time window?
• Is there CPU, memory, disk or connection pressure?
• Is the problem constant or traffic-dependent?

Interventions to avoid

Changes made before collecting evidence can conceal the root cause or expand the outage.

• Restarting Nginx repeatedly
• Increasing every timeout value
• Opening socket permissions indiscriminately
• Disabling the firewall completely
• Deleting containers and volumes
• Rolling back before preserving relevant logs

When should you seek specialist support?

If the error recurs intermittently, affects multiple services or involves a risk of downtime or data loss, it should not be treated as a single Nginx setting.

A permanent resolution often requires Nginx, the application, container networking, databases and system resources to be examined on the same timeline.