Skip to content

How to fix the 502 Bad Gateway error in WordPress

A 502 means one server passed the request to another and got no usable answer. On a WordPress site that is usually nginx, or a CDN, failing to get a page from PHP. Your content is safe. Most fixes belong to whoever runs the server, and a few checks tell you what to ask for.

By
WP Ministry
Published
Tested on
WordPress 7.1.3, PHP 8.3.35

In short

  • A 502 is written by the server in front of WordPress, not by WordPress. Your posts, settings and uploads are not touched.
  • Reload after a minute, then try from a second network. A 502 from a restart of PHP clears by itself.
  • If it began with a plugin you installed or updated, switch that plugin off from outside the dashboard.
  • On shared or managed hosting the rest is the host's. Send the exact time, the address and what changed.
  • On a server you run yourself, one line in nginx's error log says why it answered 502.

"502 Bad Gateway" comes from a server that stands in front of another. It passed the visitor's request on and got back nothing it could use. On a WordPress site the server in front is usually nginx, a load balancer or a CDN, and the one behind is PHP, which builds the page. It differs from a 503, where the server itself is not ready to take requests, usually through overload or maintenance, and from a 504, where the server in front waited and no answer came in time.

Nothing has been lost. WordPress did not write this page, and often never ran. Your posts, settings and uploads are as they were. The one thing to check afterwards is whatever was being saved at that moment, such as an order or a post you were editing.

Who can fix what

MDN's reference says that fixing a 502 probably takes investigation by the server's owners or administrators. On shared or managed hosting that is the host: you cannot see nginx or PHP-FPM, let alone restart them. What you can do is in the first three fixes and the last. The two fixes marked "with root" are for a server you run yourself, such as a VPS.

Where it goes wrong

A page request passes through each of these in turn. This one comes from the web server.

  1. Browser
  2. DNS
  3. HTTPS
  4. CDN or firewall
  5. Web server (this error comes from here)
  6. PHP
  7. WordPress
  8. Database and files

What causes it

How to fix it

Reload after a minute, then try a second network

  • Easy
  • No risk
  • About 5 minutes

  1. Step 1: Wait a minute and reload

    A restart of PHP is brief, and a busy spell passes. If the page loads, write down the time. One 502 that clears needs nothing more. One that keeps returning is worth a message to the host.

  2. Step 2: Open the site from a second network

    Use a phone on mobile data with Wi-Fi off. If the site loads there, the fault is on your side. MDN names this as the exception to "it is the server": when the site works for other visitors, check your own network settings, such as a VPN, a proxy, a firewall or DNS.

  3. Step 3: Look at the status pages

    Open the host's status page, and the CDN's if you use one. If either reports an incident, wait for it to end before you change anything on the site.

Not sure this is a 502 at all, or what kind of outage you have? The runbook for a WordPress site that is down sorts an outage by what the visitor sees.

Switch off the plugin that ends PHP's process

  • Takes care
  • Low risk
  • About 10 minutes
  • Steps tested on WordPress 7.1.3

Take this fix when the 502 began right after you installed or updated a plugin, or shows only on pages that plugin has a hand in. The dashboard may answer 502 as well, so the plugin is switched off from outside it.

  1. Step 1: Rename the plugin's folder

    In your host's file manager or over SFTP, open wp-content/plugins/ and add -off to the name of the plugin's folder. WordPress can no longer find the plugin and switches it off. Its settings are kept.

  2. Step 2: Reload the page that failed

    If it loads, that plugin was the cause. Leave it off, then install the version you had before or tell its author.

  3. Step 3: If nothing changed, put the folder back

    Rename it to what it was. The plugin was not the cause, and the next fix is the one to take.

With WP-CLI, give the plugin's folder name. The two extra options stop WP-CLI from loading plugins and the theme, so the faulty code cannot end the command as well:

bash
wp plugin deactivate plugin-folder-name --skip-plugins --skip-themes

If you cannot tell which plugin it is, how to deactivate plugins when you are locked out covers switching all of them off and bringing them back one at a time.

To undo it: Rename the folder back, or activate the plugin again.

Send the host what it needs to find the cause

  • Easy
  • No risk
  • About 15 minutes

On shared and managed hosting this is the fix for everything else on this page. Support staff can read the logs you cannot.

  1. Step 1: Write down the facts

    • The exact time of a 502, with your time zone.
    • The full address that failed, and whether every page fails or only some.
    • The words on the error page, exactly.
    • What changed last: an update, a new plugin, or a peak in visitors such as a sale or a newsletter.

  2. Step 2: Ask questions that have an answer

    text
    1. Was PHP-FPM running for my site at that time, and was it restarted?
2. What does nginx's error log say for that request?
3. Did my PHP pool reach pm.max_children?
4. Was a PHP process killed, for memory or for running too long?

  3. Step 3: Act on the answer

    A pool that reaches its limit in ordinary traffic means slow requests or a plan that is too small. How to tell a hosting fault from a site fault has a full message to copy, and the signs that the plan itself is the problem.

With root: read the logs, then restart PHP-FPM

  • Advanced
  • Low risk
  • About 20 minutes

These commands are for a Linux server that uses systemd. The file paths are the ones Debian's packages use, shown for PHP 8.4. Put your own PHP version in its place. Other distributions keep these files elsewhere.

  1. Step 1: See whether PHP-FPM is running

    The first command lists the PHP services by name, stopped ones included. The second says whether one is running and shows its most recent log lines.

    bash
    systemctl list-units --all --type=service 'php*'
sudo systemctl status php8.4-fpm

  2. Step 2: Read nginx's error log at the time of a 502

    nginx's guide gives two places for it: /var/log/nginx and /usr/local/nginx/logs.

    The line saysWhat it means
    connect() to … failed, ending while connecting to upstreamnginx could not open a connection to PHP. PHP-FPM is stopped, listens somewhere else (the next fix), or has a full queue.
    upstream prematurely closed connectionPHP took the request, and its process ended before it answered.
    upstream sent too big headerThe response's header did not fit in fastcgi_buffer_size, so nginx treats the response as invalid. Raise that setting.
    upstream timed outThat request was answered 504, not 502. PHP was slow, not gone.
    bash
    sudo tail -n 50 /var/log/nginx/error.log

  3. Step 3: Read PHP-FPM's log for the same minute

    Its place is the error_log line of php-fpm.conf.

    A line with server reached pm.max_children setting means every worker was busy: pm.max_children is the limit on requests served at once. A line with execution timed out and terminating means a worker ran past request_terminate_timeout and was killed. A child that exited on signal was ended from outside or crashed.

    bash
    grep -n "^error_log" /etc/php/8.4/fpm/php-fpm.conf

  4. Step 4: Restart PHP-FPM

    Reload the site. A restart clears a stuck service and says nothing about why it stuck. If the 502 returns, what the logs named is the thing to fix.

    bash
    sudo systemctl restart php8.4-fpm

With root: point nginx at the socket PHP-FPM listens on

  • Advanced
  • Back up first
  • About 15 minutes

  1. Step 1: See where nginx sends PHP

    bash
    sudo nginx -T | grep fastcgi_pass

  2. Step 2: See where PHP-FPM listens

    The pool file has a line beginning listen =.

    bash
    grep -n "^listen" /etc/php/8.4/fpm/pool.d/www.conf

  3. Step 3: Make the two match

    Edit the fastcgi_pass line in the server block. A socket is written with unix: before its path. An address is written as a host and a port, such as 127.0.0.1:9000.

    nginx
    fastcgi_pass unix:/the/path/on/the/listen/line;

  4. Step 4: Test, then reload

    bash
    sudo nginx -t && sudo nginx -s reload

Writing a server block from nothing? Answer a few questions in the nginx server block generator and get one for a WordPress site, built on the rules in WordPress's own nginx documentation.

To undo it: Put the old fastcgi_pass line back, test the configuration and reload nginx.

With a CDN in front: find out which side is failing

  • Easy
  • No risk
  • About 10 minutes

This is what Cloudflare's documentation says of its own 502 pages. Another CDN's will differ, so read its documentation the same way.

  1. Step 1: Read the error page

    A 502 page with Cloudflare's branding means your server answered 502 and Cloudflare passed that on. Cloudflare calls this the most common case. A blank 502 page without the branding comes from Cloudflare itself.

  2. Step 2: If your server answered it, go back to the fixes above

    Cloudflare's advice is to contact your hosting provider with the error code and message, the time with its time zone, and the address that failed. It says the same for an error page that does not mention Cloudflare at all.

  3. Step 3: If Cloudflare answered it, write to Cloudflare

    Its support asks for the time with its time zone, the address that answered 502, and what your browser shows at /cdn-cgi/trace on your domain.

Cloudflare also has codes of its own, 520 to 526, for other failures to reach a server. 521, for one, means the server refused Cloudflare's connections. Its documentation has a page for each.

When to get help

Stop when the 502 has lasted more than a few minutes, the plugin you last changed is off, and the host says the server is healthy. The cause is then in logs you cannot see. On a server you run yourself, stop when the logs name nothing you recognize. Restarting PHP again and again clears the symptom and leaves the cause in place.

Common questions

Is a 502 my fault or my host's?

Most often it is on the server's side, which on shared or managed hosting means the host's. There are two exceptions you can settle yourself: your own network, and a plugin that ends PHP's process. The first two fixes cover them.

Why does a 502 come and go?

Because its causes do. A restart is over in moments. A busy spell fills PHP's workers and then eases. A plugin that crashes PHP does it only on the pages that run its code. Note which pages fail and at what times: that pattern is what the host needs.

Will raising PHP's memory or time limit fix a 502?

Not as a rule. A page that passes PHP's own memory_limit or max_execution_time is stopped by PHP, which reports it, and the visitor gets a 500 with "There has been a critical error on this website." Those have fixes of their own: Allowed memory size exhausted and Maximum execution time exceeded. A 502 means the server in front got no usable answer at all. That is what separates it from a 500 Internal Server Error, where the server behind did answer, with an error.

More on this subject

Would you rather we fixed it?

Emergency Fix is $99. Site down or checkout broken. Goes to the front of the queue. No fix, no fee. 30-day warranty. It starts with a free diagnosis.

Get a free diagnosis