What a 502 Bad Gateway Actually Means
A 502 Bad Gateway means a proxy that is still running received an invalid response, or no HTTP message it could relay, from the upstream it called.
The browser talks to Nginx, Apache with a proxy, a load balancer, or a CDN. That middle box asks PHP-FPM, Node, or another app for the page. When the app is dead, on the wrong socket, or replies with garbage, the middle box returns 502. The app failed. The visitor's click did not.
Use the status code, not the branded error page, to pick the next guide. A crash inside the site is a 500 error. A server that is up but refusing work is a 503 Service Unavailable. A proxy that waited too long is a 504 Gateway Timeout. A rule that refuses the visitor is a 403 Forbidden.
| Code | What the gateway is saying | Where to look |
|---|---|---|
| 502 Bad Gateway | Proxy got an invalid or empty reply from upstream | App process, socket or port, FastCGI buffers |
| 504 Gateway Timeout | Proxy waited and the upstream did not finish | Slow PHP, a hung query, the read timer |
| 503 Service Unavailable | Server is up but will not take the request now | Entry processes, maintenance, overload |
| 500 Internal Server Error | The app threw while building the page | .htaccess, a plugin, a PHP fatal |
| 403 Forbidden | A rule refused this visitor or file | Permissions, ModSecurity, a deny rule |
- The proxy is usually still running. The upstream reply is what failed.
- Connection refused, a bad socket, and an oversized header are 502 work.
- A pure wait belongs with the 504 guide, not with a larger buffer.
Quick Fixes for a 502 Bad Gateway
Work the checks in order and stop when the URL returns 200. A second failure means read the log, not reload again.
- Reload the URL. A single blip clears. If the 502 returns at once, continue.
- Open a private window, or load the same URL on mobile data. If that works, the fault is a cached copy, an extension, or a VPN on that device.
- If every network fails, the origin is sick. On a VPS, read the gateway log, then restart the app service.
- On WebJi® shared or cPanel hosting you cannot restart PHP-FPM from the panel. Email support@webji.services with the exact URL and the time. The office phone is not the support line.
- Confirm disk and memory with df -h and free -m. A full disk or an out-of-memory kill shows up as 502 even when the config is unchanged.
The log line picks the next section. Connection refused is the PHP-FPM section. A timeout belongs with the 504 guide linked above. An oversized header is the buffer section below.
PHP-FPM Workers That Cause a 502 at Peak
A 502 that shows up only when the site is busy usually means PHP-FPM has no free child left. Each request holds one child until PHP finishes. When every child is busy, the proxy fails the new request.
On a VPS running PHP 8.3 the pool file is /etc/php/8.3/fpm/pool.d/www.conf. The settings that matter are pm (dynamic, static, or ondemand) and pm.max_children. The ceiling is RAM you can give PHP, divided by the average process size.
Measure that size with ps --no-headers -o rss -C php-fpm8.3 during normal traffic. A typical WordPress child is about 50–100 MB. On a 2 GB server with about 600 MB left for PHP and a 75 MB average, set pm.max_children to 8. A higher ceiling gets workers killed, and those kills look like random 502s.
Then run systemctl restart php8.3-fpm, or php8.2-fpm if that is the version installed. On a WebJi® shared account this file is not yours to edit. The same symptom is an entry-process cap, and support reads that graph with you.
Nginx Timeouts and Buffers Behind a 502
Open /var/log/nginx/error.log, or the path set in nginx.conf. The phrase on the line is the diagnosis. Change one directive, run nginx -t, reload Nginx, and retest that URL in a private window.
| Log phrase | What failed | What to change |
|---|---|---|
| connect() failed (111: Connection refused) | Nothing is listening on the proxy target | Start PHP-FPM or the app, and confirm the port or socket |
| Permission denied | The socket exists but the proxy user cannot use it | Match the pool listen owner to the Nginx user |
| upstream timed out | The app accepted the connection and did not finish | Treat it as a 504 and shorten the work |
| upstream sent too big header | Response headers exceeded the FastCGI buffer | Raise fastcgi_buffer_size and fastcgi_buffers, then reload |
| no live upstreams | Every backend failed its check | Restore one healthy app process before tuning timers |
A refused connection is not fixed by a longer timer. Raise proxy_read_timeout or fastcgi_read_timeout only when the log says the upstream timed out, and only by a small step. If the app needs minutes, take that work off the web request. That wait is a 504, not a 502 you hide.
The line upstream sent too big header means the FastCGI headers, often a pile of Set-Cookie values, did not fit the buffer. Raise fastcgi_buffer_size and fastcgi_buffers one step, reload, and fetch the URL again. Stop when the 502 is gone.
Apache with mod_proxy fails the same two ways: ProxyPass points at the wrong port, or ProxyTimeout is shorter than the app. Match the port the app listens on, then reload Apache.
What a Cloudflare 502 Means
A Cloudflare-branded 502 means Cloudflare reached your origin and did not get a valid response. Ask the origin directly with curl -I --resolve yourdomain.com:443:ORIGIN_IP https://yourdomain.com. A 200 from the origin and a 502 through Cloudflare means the CDN cannot finish the connection. A 502 from the origin means the app behind Nginx is still the fault.
Neighbour codes are a different job. 522 is a timeout: the origin firewall is dropping Cloudflare, or the origin is down. 521 means the origin refused the connection and the web server is stopped. 525 is an SSL handshake failure: put a valid certificate on the origin and use Full (strict).
Fix the origin and the Cloudflare 502 leaves with it. A cached page at the edge can still look fine while URLs that miss the cache fail.
How to Prevent the Next 502 Bad Gateway
Leave RAM headroom so pm.max_children fits without swap. A pool sized to the last byte of memory fails as soon as a backup or a crawl starts.
Watch the gateway error log, rather than only whether the homepage loads. A rising count of connect() failed or no live upstreams is the 502 starting. WebJi® states a 99.9% uptime target; a 502 on your account is still diagnosed from your log line.
On a VPS, a health URL that returns 200 only when PHP and the database answer shows the upstream dying before Nginx does. On shared hosting, email support@webji.services when the same URL returns 502 twice and you have no SSH. Say what changed last: a plugin, a PHP version, or a deploy.
Frequently Asked Questions
How do I fix a 502 Bad Gateway error?
Reload once. If it returns, read the gateway error log. Connection refused means restart PHP-FPM or the app. A timeout is the slow-upstream case. A permission error means the socket path is wrong. On WebJi shared hosting, email support@webji.services with the URL and the time. Do not restart the server yourself.
What causes 502 errors on my website?
The proxy is up, and the upstream is not answering with valid HTTP. Typical causes are a dead PHP-FPM pool, a wrong port or socket, response headers larger than the FastCGI buffer, a full disk, or an out-of-memory kill.
Is a 502 error my fault or my host's?
If a private window and a second network still fail, the origin is at fault: your app, the proxy config, or the host PHP pool. If only your browser fails, clear the cache or pause a VPN. A new domain name does not fix it.
How do I restart PHP-FPM?
On a VPS, run systemctl restart php8.3-fpm, using the PHP version the pool actually runs. On WebJi shared or cPanel hosting the pool is managed for you. Email support@webji.services. cPanel has no customer button that restarts the host PHP-FPM service.
Why does a 502 appear only during high traffic?
Every busy PHP request holds one child. When pm.max_children is full, new requests fail at the proxy. Size the ceiling from usable RAM divided by average process memory. Do not set it higher than memory allows, or the kernel kills workers.
What does a 502 from Cloudflare mean?
Cloudflare reached your origin and got an invalid or empty response. Test the origin IP directly. A 522 is a timeout, a 521 is a refusal, and a 525 is an SSL handshake failure between Cloudflare and the origin. Fix the origin and the CDN error clears with it.
Is a 502 Bad Gateway permanent?
No. It lasts only while the upstream is down, pointed at the wrong socket, or out of workers. One reload often clears a blip. A 502 on every URL stays until that log line is fixed.
Does a 502 Bad Gateway mean I am blocked?
No. A block or a permission rule is usually a 403 Forbidden. A 502 means the gateway could not relay a valid response from the upstream app.
Is a 502 Bad Gateway a hack?
Not by itself. It means the proxy and the app stopped talking. Read the error log and recent plugin or deploy changes before you treat it as a compromise.