502 Bad Gateway and 504 Gateway Timeout: Causes and Solutions

Seeing "502 Bad Gateway" or "504 Gateway Timeout" instead of content when you open your site is frustrating. The good news: these errors usually stem from specific, solvable causes. This guide explains what the two errors mean, their differences and their step-by-step solution.

Related reading: PHP-FPM configuration · Reading Linux server logs · systemd service management

What Do These Errors Mean?

Modern web servers often act like a gateway: they receive the incoming request and forward it to a backend upstream service — for example PHP-FPM, a Node.js application or another server. 502 and 504 tell you that something went wrong during this forwarding.

In short: 502 usually means "the backend service is crashed or broken", while 504 means "the backend service is running but very slow".

Common Causes of 502 Bad Gateway

• The upstream service is not running: PHP-FPM or the application service is stopped. Check with systemctl status.
• Wrong socket/port: The upstream address in the web server's configuration does not match the service's real address.
• The service is crashing: The application starts but crashes immediately due to an error — check the logs.
• Permission problem: The web server cannot access the upstream socket file.

Common Causes of 504 Gateway Timeout

• A very slow operation: A PHP script or query runs longer than the allowed time.
• Exhausted worker pool: All PHP-FPM workers are busy, a new request queues and times out.
• A slow database: The application stalls while waiting for a database response.
• A low timeout value: The web server's upstream wait time is too short for the real need.

Step-by-Step Solution

When you encounter a gateway error, proceed in order:

• 1. Check the upstream service: systemctl status php8.3-fpm — is the service running? If not, start it.
• 2. Look at the web server error log: /var/log/nginx/error.log often tells the exact cause of the error directly.
• 3. Verify the upstream address: Is the socket/port in the configuration the same as the address the service actually listens on?
• 4. For 504, look at time/resources: Is there a slow query, an exhausted worker pool, or a low timeout?
• 5. Restart the service: For a temporary stall, restarting the upstream service often resolves it.

Frequently Asked Questions

The 502 error went away on its own, is the problem solved?

No. A 502 that goes away on its own usually shows that the service temporarily crashed and restarted. It will recur; inspect the logs and find the root cause.

Is the error on my site or on the server?

502/504 are server-side errors — there is nothing the visitor can do. The problem is in the communication between the web server and the backend service.

I see 502 while using a CDN, why?

A 502 shown by the CDN can mean the CDN cannot reach your origin server. Check that your origin server is running and that the CDN is connecting to the correct address.