How to Fix a 502 Bad Gateway Error in Nginx

It's a mistake.502 Bad GatewayThis means that Nginx has failed to take a valid and usable response from the server as a gateway or proxy. The service may be PHP-FPM, an application, Apache, or a container. The 502 page itself does not indicate the cause; a blind restart may temporarily raise the site, but it eliminates evidence to understand crash, faulty socket, or lack of capacity.

Quick answer:Enter an exact time and the wrong URL, then check the same error log for Nginx and upstream status at the same time. If upstream stops, find the cause of the stop of log and memory pressure; if it is active, apply the socket/port, permission, and config.nginx -tWeigh it.

First, identify the fault zone.

• Are all URLs 502 or are they just PHP/API routes?
• Is it a permanent error or only occurs when traffic is high?
• The static file opens like an image?
• Is the same thing happening on the server and on the Internet?
• Has it started right after deployment, update or config change?

If the static file is healthy but the PHP page is faulty, the Nginx path to PHP-FPM is the prime suspect. If only one API makes an error, check upstream for the same route.

What's the difference between 502 and 504?

In 502, the payment gatewayway usually did not establish an upstream connection, the connection was quickly closed or received an unreliable response.504 Gateway TimeoutConnection or processing takes longer than the allowed time limit. This is not an absolute limit and error log text is more decisive than page number.Fixed the 504 error.It focuses on timeout and long processing.

Evidence you must keep before you change.

Enter the time zone, URL, method, status, request ID, and last change. If the reverse proxy or other CDN is in front of Nginx, specify which layer generated the error page. Heads and page appearance are only a hint; match the log layers with a shared timestamp. Do not copy cookies, tokens, and customer data in the public tickets.

Low-risk assessment of the situation

systemctl status nginx --no-pager
systemctl --failed
ss -lntp
free -h
df -h
df -i

These commands primarily read the status. The name of the PHP-FPM service is dependent on the PHP distribution and version; find it from existing units or real config and don't guess. A full disk or inode can disrupt a socket, log, or temporary file.

Read the Nginx Log Error

Messages like connection refused, no socket file, permission denied, prematurely closed connection or upstream sent invalid response each have different paths. Just don't separate the last line; see host, upstream, request and several lines around the same timestamp.

• Connection refused:The service on the expected port is not listening or is restarting.
• No such file or directory:Socket is not built or the configuration path is old.
• Permission denied:The web server user has no access to the socket or parent path.
• Upstream closed connection:The program crashed, the limit was broken or the response was closed early.
• Invalid header:The protocol service or response did not generate the expected proxy.

Is Upstream really available?

For upstream networking, the listener can be connected to thessFor the Unix socket, see Existence, Ownership and Permission path. Local testing must have the correct host and protocol; HTTP requests to the port that FastCGI speaks to are not a valid test. In Docker, localhost is not the same as host or container inside a container.

PHP-FPM: The most common WordPress scenario

Check the status of the unit, journal, and log pool in the same time frame. PHP-FPM may be active, but all workers are involved, the pool is wrong, socket is different, or processes crash one after another.active (running)The rows, number of active/idle processes, slow log and duration of requests give a better picture.

Socket or TCP?

The amount.fastcgi_passIn Nginx, we have to be exactlylistenAfter PHP upgrade, the socket name may change and Nginx will still point to the previous version path. Creating a symlink to hide the difference in version of the solution is not stable; configure active and synchronize service lifecycle.

Permission Socket

Owner, group and socket mode must allow Nginx user connection.chmod 777It weakens security and may disappear after restarting. Modify the property settings in your pool configuration and then test with minimal access.

Don't take out Crash and OOM.

If PHP or the program suddenly disappears, check the kernel and the service journal for OOM, segfault, and exit code. Automatic worker augmentation without memory calculation can increase OOM. First measure the memory of each process, the container/systemd ceiling, and concurrent traffic; then change the capacity of the pool.

When 502 just happens to be under the bar

Put the error rate alongside the request rate, latency, worker queue, CPU, RAM, and dependencies. An external database or API can keep workers from having a pool of acceptance capacity. Worker increment is only useful when RAM and CPU are sufficient; otherwise swapping and crash will increase.

Proxy Chain and Docker.

In the CDN → Nginx → container → app chain, each hop has a separate name, port, network and health. The Docker service name is only used in the relevant network resolve and published port is different from container port. Do not hard-code the container's fixed IP. Check the container status, restart count, health and log of the app alongside the proxy log.

What are the most likely things to happen after the deployment?

• The name or port of the service has changed, but the proxy configuration is old.
• PHP-FPM has created another socket.
• Environment or secret files are not available in the program
• The migration database failed and the process is out.
• The file or socket ownership is different in the new image.
• Healthcheck will be successful before the service is actually ready.

In this situation, diff release and log startup are more useful than pipe restarts. If you have a defined and tried rollback, a controlled return can reset the service; however, written data and migration compatibility must be checked before rollback.

The correction order from low-risk to advanced

1. Record the error range and time and keep logs.
2. Read upstream status, listener, disk and memory.
3. Compatible Nginx's effective configuration with the actual upstream.
4. The syntax issudo nginx -tCheck it out.
5. If the configuration is correct, remove the cause of the upstream stop and start it controlled.
6. Recharge or restart only for the change needed.
7. Smoke test static, dynamic, login and main transaction from inside and out.
8. After the resuscitation, record the root cause and the preventive action.

What are we not doing?

• Clear the log or restart the continuous before collecting evidence.
• Extending the timeout for the error connection refused
• Giving public permission to sockets and files
• Increasingly, PHP workers
• Trusting the status of service without a real request.
• Edit the production configuration without backup and syntax test
• Attributing each 502 to Nginx, without upstream review.

Preventing the Repeat of Mistakes

For the actual healthcheck endpoint, set the 502 rate, restart service, queue, memory, disk, and certificate alert. The deploy must have a config test, actual readiness, and rollback. Create the name of the socket or service in automation from the unit source. Rotate logs and pass the request ID between the proxy and the program.

When is special intervention needed?

If 502 is rotating, you have multiple proxies, or a restart works for just a few minutes, further testing on the production may take a while.Monthly management of the serverIt can perform Nginx, PHP-FPM, system and database log correlation and determine the cause before the capacity changes.

Common Questions

Does rebooting Nginx fix the 502 error?

Only in some instances, and usually temporarily. If the upstream is stopped or the address is wrong, reboot Nginx will not fix the cause.

Why do I see 502 error after PHP upgrade?

One of the most common reasons for the socket or pool disagreement is that the new version of thefastcgi_passIt's active; match the actual service and configuration.

Does 502 mean a database failure?

Not necessarily. The database can crash or delay a program, but 502 is directly about the payment gatewayway and upstream connection.

Why are only some requests 502?

There may be an unhealthy backend, different route, data-dependent crash, or a variable pool saturation; check the request ID and upstream selected.