Troubleshooting · Troubleshooting
How to Fix the 502 Bad Gateway Error in WordPress
Short answer
A 502 Bad Gateway error means the gateway in front of WordPress got an invalid reply from PHP-FPM or the origin server. Restart PHP-FPM, match the Nginx socket path to the PHP-FPM pool, and check the error logs for the exact cause. If the site sits behind Cloudflare, read the error page first to tell an origin 502 from a Cloudflare 502.
Key takeaways
- A 502 error means the gateway got a bad reply from upstream, not that the gateway itself is down.
- PHP-FPM being stopped, out of workers, or on a wrong socket path is the most common WordPress cause.
- A Cloudflare-branded 502 comes from your origin server, while a plain unbranded 502 comes from Cloudflare.
- The PHP manual says pm.max_children sets the limit on simultaneous requests served by a pool.
- WordPress.org recommends PHP 8.3 or greater as of November 2026, and a PHP change can break the socket path.
- Log errors with WP_DEBUG_LOG on a live site and keep WP_DEBUG_DISPLAY set to false.
What does the 502 Bad Gateway error mean in WordPress?
A 502 Bad Gateway error means a gateway or proxy received an invalid reply from the server behind it, so WordPress never gets a chance to build the page.
MDN Web Docs defines the 502 status as a server acting as a gateway or proxy that received an invalid response from the upstream server.
In a WordPress setup, the chain is usually a browser, then Nginx or Cloudflare, then PHP-FPM, then WordPress itself. PHP-FPM is the process manager that runs PHP code for WordPress.
If a plain HTML file loads but every WordPress page shows 502, the fault sits between the web server and PHP. The browser and the front server are working, but the step behind them is not.
How is a 502 different from a 503 or 504 error?
A 502 means the gateway got a bad reply from upstream, a 503 means the server is briefly unable to serve requests, and a 504 means the gateway got no reply in time.
| Code | What happened | First place to look |
|---|---|---|
| 502 Bad Gateway | Gateway got an invalid reply from upstream | PHP-FPM, Nginx error log, origin server |
| 503 Service Unavailable | Server is unable to handle the request for now | Server load, maintenance mode, resource limits |
| 504 Gateway Timeout | Gateway got no reply from upstream in time | Slow upstream, timeouts, overloaded PHP workers |
| 500 Internal Server Error | Server hit an error while running the request | PHP fatal error, WordPress debug log |
MDN Web Docs adds that a gateway sends a 504 when it receives no HTTP response at all, while a 502 follows an invalid response.
The code matters because each one points at a different fix. A 502 sends you to the link between the gateway and PHP, not to maintenance mode or a slow page.
What causes a 502 Bad Gateway error on a WordPress site?
The most common causes are a stopped PHP-FPM service, an exhausted PHP worker pool, a wrong socket path after a PHP change, and a broken reply from the origin server.
| Cause | Signal | Likely fix |
|---|---|---|
| PHP-FPM stopped or crashed | Every PHP page fails, static files load | Restart PHP-FPM |
| Worker pool exhausted | 502 appears only at busy times | Raise pm.max_children within your RAM limit |
| Wrong socket path | Log says no such file or connection refused | Match fastcgi_pass to the pool listen value |
| Bad plugin or theme code | 502 starts after an update | Deactivate plugins and check the debug log |
| Broken gzip at the origin | Plain Cloudflare 502 page | Turn off compression at the origin and retest |
A PHP change is a frequent trigger. WordPress.org recommends PHP 8.3 or greater as of November 2026, and a version change also changes the PHP-FPM socket name, so an old path in Nginx stops working.
Check the WordPress hosting requirements before you change a PHP version, so the new version still matches what WordPress needs.
How do you check whether the error is site-wide or only for you?
Check the site in a second browser, on mobile data, and ask someone in another place to load it before you change any server setting.
- Hard refresh the page with Ctrl+F5 on Windows or Cmd+Shift+R on Mac.
- Open the site on mobile data, away from your home or office network.
- Load the homepage, one post, and
wp-adminto see if all of them fail. - Ask your host whether other sites on the same server show the same error.
A 502 that appears for everyone is a server problem. A 502 that appears only for you points at your network, VPN, or a cached error page in your browser.
Cloudflare's own 502 guide, updated 12 October 2026, asks support callers to send the exact URL, the time with its timezone, and the output of yourdomain.com/cdn-cgi/trace. Gather those 3 items before you open a ticket.
How do you fix a 502 error when PHP-FPM is down or overloaded?
Restart PHP-FPM, then check that its pool has enough workers for your traffic, because a dead or full pool is the most common WordPress cause.
- Check the service with
sudo systemctl status php8.3-fpm, using your own PHP version in place of 8.3. - Restart it with
sudo systemctl restart php8.3-fpmand reload the site. - Read the PHP-FPM log for the line
server reached pm.max_children setting, which means every worker was busy. - Open the pool file, usually
/etc/php/8.3/fpm/pool.d/www.conf, and raisepm.max_childrenonly as far as your RAM allows. - Reload PHP-FPM with
sudo systemctl reload php8.3-fpmand watch the log during the next busy period.
The PHP manual says pm.max_children sets the limit on the number of simultaneous requests that will be served, and it is a mandatory setting.
The same manual lists 3 modes for pm: static, ondemand, and dynamic. With ondemand, idle workers are killed after pm.process_idle_timeout, which defaults to 10 seconds.
Do not raise the worker count without checking memory. Each worker uses RAM, so a very high limit can push the server out of memory and crash PHP-FPM again. See how many PHP workers you need for WordPress to size the pool.
On shared hosting you usually cannot restart PHP-FPM yourself. Use the host control panel to restart PHP, or ask support to check the service and the pool for your site.
How do you fix a 502 caused by a wrong PHP-FPM socket or a bad plugin?
Match the socket path in Nginx with the listen value in the PHP-FPM pool file, then rule out a plugin that crashes PHP workers.
- Open the Nginx site file and note the
fastcgi_passvalue, such asunix:/run/php/php8.3-fpm.sock. - Open the pool file and compare it with the
listenvalue there. - List the real sockets with
ls -l /run/php/and fix the path that does not match. - Run
sudo nginx -tto check the config, thensudo systemctl reload nginx.
A socket mismatch often follows a PHP update, because the version number is part of the socket name. Update the PHP version and the socket path together, as described in how to update the PHP version in WordPress.
If the socket is right, check for a plugin that kills PHP. Rename the wp-content/plugins folder to plugins-off over SFTP, reload the site, then rename it back and reactivate plugins one by one.
WordPress debugging can name the faulty file. The Debugging in WordPress guide says WP_DEBUG defaults to false, WP_DEBUG_LOG writes errors to wp-content/debug.log, and WP_DEBUG_DISPLAY defaults to true.
On a live site, log errors instead of showing them. Set WP_DEBUG to true, WP_DEBUG_LOG to true, and WP_DEBUG_DISPLAY to false, then turn debug mode off when you finish.
How do you fix a 502 error behind Cloudflare?
First read the error page itself, because a Cloudflare-branded 502 comes from your origin server while a plain unbranded 502 comes from Cloudflare.
Cloudflare's Error 502 or 504 guide lists 2 possible causes and says errors from your origin web server are the most common cause.
A branded page means your origin sent a standard 502 or 504 to Cloudflare. Fix it on the origin with the PHP-FPM and socket steps above, and ask your host to check server loads, crashes, and network failures.
An unbranded page can come from a compression fault at the origin. Cloudflare says the origin may serve gzip content without updating the content-length header, or serve broken gzip content, so turn off compression at the origin to confirm it.
- Note whether the page is branded or plain, and copy the Ray ID shown on it.
- Bypass Cloudflare by loading the origin directly, if your host gives you a direct test address.
- Check that the origin answers for the exact hostname in the failing URL.
- Ask your host to check the origin logs at the same time the error appeared.
If you use Cloudflare Tunnel, a 502 can mean cloudflared cannot reach the local service in its ingress rule. Check that the service runs and that the route uses the right protocol and port. See how to set up Cloudflare for WordPress for the normal proxy setup.
How do you fix a 502 caused by response headers that are too large?
Raise fastcgi_buffer_size in Nginx when the log says upstream sent too big header, because the default buffer holds only one memory page.
Nginx documentation says the default fastcgi_buffer_size is 4k or 8k, equal to one memory page, and that a response is treated as invalid when its first part exceeds the buffer.
Large cookies and login headers are the usual cause. The first part of a response holds the status line and headers, so long cookies can overflow a 4k buffer even when the page body is small.
- Find the log line with
sudo tail -n 100 /var/log/nginx/error.logand look forupstream sent too big header. - In the PHP location block, add
fastcgi_buffer_size 32k;andfastcgi_buffers 16 16k;. - Run
sudo nginx -t, thensudo systemctl reload nginx. - Reload the failing page and check the log for a fresh 502.
Do not set buffers to megabytes to be safe. Each connection uses its own buffers, so very large values waste memory on a busy server.
How do you know the 502 error is fixed?
Load the homepage, a post, and wp-admin in a fresh browser session, and confirm each returns a 200 status instead of 502.
- Open the homepage and 2 or 3 posts that failed before.
- Log in to
wp-adminand open the dashboard and one edit screen. - Run
curl -Ion your homepage URL and look forHTTP/2 200in the reply. - Check the Nginx and PHP-FPM logs for new upstream errors at the same time.
- Repeat the check after 30 minutes, in case the fault only appears under load.
A single good load is not proof, so test again during a busy period before you call the job done.
When should you contact your host about a 502 error?
Contact your host when the error affects every page, returns after a PHP-FPM restart, or needs a server log or setting you cannot reach.
- The 502 appears on every page, including
wp-admin, for more than a few minutes. - PHP-FPM will not start, or it stops again soon after a restart.
- The Nginx error log names a socket or permission problem you cannot edit.
- The error started right after a server move, a PHP change, or a host maintenance window.
- Your plan has hit a memory, worker, or entry process limit.
Send the host the failing URL, the time with its timezone, your PHP version, and what changed just before the error. If you use Cloudflare, add the Ray ID and the output of /cdn-cgi/trace from your domain.
Ask the host to confirm 3 things: that PHP-FPM is running, that the pool has free workers, and that Nginx points at the right socket. Those 3 answers cover most WordPress 502 errors. If 502 errors keep returning, check what a good uptime percentage is for hosting before you judge the host.
What mistakes should you avoid?
Do not treat a server error as a browser problem, and do not change several settings at once.
- Clearing the browser cache is not a fix for a server-side 502, though it can clear a stale error page after the server recovers.
- Raising
pm.max_childrenwithout checking RAM can crash PHP-FPM again. - Setting Nginx buffers to megabytes wastes memory on every connection.
- Showing debug errors on a live site leaks file paths to visitors, so keep
WP_DEBUG_DISPLAYfalse there. - Downgrading Cloudflare SSL to Flexible to dodge a 502 hides a certificate problem instead of fixing it.
- Editing
wp-config.phpbelow the line that says stop editing can leave your change unread, so place debug lines above it.
Frequently asked questions
Can a 502 Bad Gateway error fix itself?
Yes, sometimes. A short 502 can clear when a crashed PHP-FPM service restarts, a deploy finishes, or a traffic spike passes. If the error lasts more than a few minutes or returns at busy times, it has a real cause such as a dead service, a full worker pool, or a wrong socket path, and it needs the checks in this guide.
Does clearing my browser cache fix a 502 error?
No, not on its own. A 502 is a server-side error between the gateway and PHP-FPM or the origin server, so clearing your cache cannot repair it. A hard refresh can help only after the server is fixed, when your browser still shows a saved copy of the error page instead of the live site.
Why does my site show a 502 error only after a PHP update?
A PHP update changes the PHP-FPM service name and socket path, because the version number is part of both. If Nginx still points at the old socket, it cannot reach PHP and returns a 502. Update the fastcgi_pass path to match the new socket, run nginx -t, reload Nginx, and restart PHP-FPM.
Is a 502 error a sign that my site was hacked?
No, a 502 on its own is not a sign of hacking. It means the gateway got an invalid reply from the server behind it, which is usually a stopped service, a full worker pool, or a config mismatch. Check the server logs and the debug log first. Only treat it as a security matter if the logs show strange files, unknown admin users, or odd requests.
How long should I wait before contacting my host about a 502 error?
Wait a few minutes for a short outage, then contact your host if every page still shows 502. Send the failing URL, the time with its timezone, your PHP version, and what changed just before the error started. If you use Cloudflare, add the Ray ID from the error page and the output of the trace page on your domain.
Sources
- Error 502 or 504 Cloudflare Docs
- 502 Bad Gateway MDN Web Docs
- PHP-FPM Configuration PHP Manual
- Module ngx_http_fastcgi_module Nginx Documentation
- Debugging in WordPress WordPress Developer Resources
- Requirements WordPress.org
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
