Debugging WordPress white screens and 500 errors

When the site goes blank

Few things make a site owner's stomach drop like opening the website and finding nothing: a white page, a short "critical error" message, or a bare "500 Internal Server Error". No menu, no content, sometimes no way into the dashboard either.

The good news is that these failures look dramatic but usually have ordinary causes: a plugin that clashes with an update, a theme that needs a newer PHP version, a site that ran out of memory, a configuration file with a typo. Almost all of them can be fixed without a developer, and without losing any content. Your posts, pages and orders are safe in the database; what broke is the code that displays them.

This guide shows how to read the symptoms, find the actual error message, fix the most common causes, and decide when it is time to restore a backup or call your host. It is part of our WordPress maintenance series, and it builds on the recovery steps in the article on safe updates.

Read the symptoms first

What you see on screen already narrows things down.

What you seeWhat it usually means
"There has been a critical error on this website."A PHP fatal error, caught by WordPress. A plugin or theme is the most likely cause, and WordPress has probably emailed the site admin.
A completely blank white pageA PHP fatal error with error display switched off, often on older setups. Same causes, but no email or message to help.
"500 Internal Server Error"The web server itself failed to process the request. Common causes: a broken .htaccess file, wrong file permissions, a PHP crash, or a server limit.
"502 Bad Gateway" or "504 Gateway Timeout"The server took too long or a component behind it stopped responding. Often a host-side problem or a slow, heavy process.
"503 Service Unavailable"The server is overloaded or temporarily down for maintenance. Usually host-side, or an aggressive traffic spike.
"Briefly unavailable for scheduled maintenance"An update was interrupted and WordPress is still in maintenance mode.
"Error establishing a database connection"WordPress cannot reach its database. Wrong credentials in wp-config.php, or the database server is down.

This guide focuses on the first three, which are the ones you can usually fix yourself. The others get a short answer each in the sections below.

The first five minutes

Before editing a single file, spend a few minutes gathering facts. They often point straight at the cause.

  1. Is it the whole site or part of it? Check the homepage, an inner page, and /wp-admin in a private browser window. A blank admin with a working front end (or the reverse) is a strong clue.
  2. What changed recently? An update, a new plugin, a theme edit, a PHP version switch by the host, a migration. Most white screens appear minutes after a change. Your maintenance log, or the update emails WordPress sends, will tell you.
  3. Check the admin inbox. If WordPress caught the error, it sent an email with the name of the plugin or theme at fault and a link to Recovery Mode. Look in spam too.
  4. Check your host's status page. If the host has an outage, nothing you change on the site will help.
  5. Take a backup of the broken state if your host makes it easy. It sounds odd, but it protects you if a fix attempt makes things worse, and it preserves any orders or form entries received since the last backup.

Then follow the rule that saves the most time in all of troubleshooting: don't guess, find the error message first. A white screen hides the cause, but WordPress and the server almost always record it somewhere.

Find the real error

There are three places to look, from easiest to most technical.

1. The Recovery Mode email

Since version 5.2, when WordPress hits a fatal error on a normal page load, it shows the "critical error" message and emails the site admin. The email names the plugin or theme involved, includes the error details, and contains a special link to log in using Recovery Mode. In Recovery Mode the faulty extension is paused for you alone, so you can reach the dashboard, deactivate it, and exit. Visitors keep seeing the error until you fix it.

The email goes to the address in Settings > General, so keep that current and make sure your site can send email reliably.

2. The WordPress debug log

If there is no email, turn on WordPress's own error log. Open wp-config.php in the site's root folder (with your host's file manager or SFTP) and add these lines above the line that says "That's all, stop editing!":

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

If WP_DEBUG is already defined as false, change that line rather than adding a second one. Reload the broken page, then open wp-content/debug.log. Scroll to the bottom and look for a line starting with "PHP Fatal error". It names the file and line that failed, and the folder path tells you which plugin or theme it belongs to, for example wp-content/plugins/plugin-name/....

This setup writes errors to the file without showing them to visitors. Even so, turn debugging off again (set WP_DEBUG back to false) and delete debug.log once you have fixed the problem: the file can reveal details about your site, and logging slows things down slightly.

3. The server error log

For 500 errors that happen before WordPress even loads, the answer is in the server's own error log. Most hosting panels have an "Error log" or "Logs" section; on others the file sits in the site's root or a logs folder. Look for entries with the time of your failed request. Messages about .htaccess, permissions, or "premature end of script" point to server-level causes rather than WordPress code.

Common causes and how to fix them

Work through these in order. They are listed roughly from most to least common.

A plugin

The usual suspect, especially right after an update. If the error message names a plugin, deactivate that one. If you cannot reach the dashboard:

  • With file access, rename the plugin's folder in wp-content/plugins (add -off to the name). WordPress deactivates it automatically.
  • If you don't know which plugin, rename the whole plugins folder to plugins-off. If the site comes back, rename it to plugins again, then reactivate plugins one at a time from the dashboard until the error returns. The last one you activated is the culprit.
  • With WP-CLI: wp plugin deactivate plugin-name, or wp plugin deactivate --all to test them all at once.

Once you know which plugin it is, roll it back to the previous version, report the problem to the developer, or replace it.

The theme

If disabling plugins doesn't help, test the theme. Rename the active theme's folder in wp-content/themes; WordPress falls back to a default theme such as Twenty Twenty-Five if one is installed. If the site loads, the theme (or a child theme edit, often in functions.php) is the cause. Keep at least one default theme installed for exactly this reason.

Out of memory

A log line containing "Allowed memory size of ... bytes exhausted" means PHP ran out of memory. WordPress requests 40 MB for the front end by default (64 MB on multisite) and 256 MB for the admin. You can raise the front-end figure in wp-config.php:

define( 'WP_MEMORY_LIMIT', '256M' );

This only works up to the limit your host sets for PHP. If the error keeps showing the same number, ask the host to raise PHP's memory_limit, or change it in your hosting panel. And treat more memory as a stopgap: if one plugin suddenly needs far more than before, that plugin has a problem.

PHP version

If the host upgraded PHP recently, or you did, old plugins and themes may use code that newer PHP no longer accepts. The debug log will show errors such as "Call to undefined function". The quick fix is to switch the site back to the previous PHP version in the hosting panel; the lasting fix is to update or replace the outdated code, then upgrade PHP again.

A broken .htaccess file

On Apache and LiteSpeed servers, a typo in .htaccess (often added by a security or caching plugin) causes an instant 500 error on every page. Rename the file to .htaccess-old and reload. If the site comes back, go to Settings > Permalinks and click Save to generate a clean one, or create it with WordPress's default rules:

# BEGIN WordPress
RewriteEngine On
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
# END WordPress

Then add back any custom rules from the old file one block at a time. The file is hidden by default, so switch on "show hidden files" in your file manager or FTP program.

File permissions

After a migration or a manual upload, wrong permissions can cause 500 errors or blank pages. The standard values are 755 for folders and 644 for files, with wp-config.php often tighter (440 or 400, depending on the host). Never use 777: it lets anyone on the server write to the file. If you are unsure, ask your host to reset permissions; many do it in a click.

Stuck in maintenance mode

"Briefly unavailable for scheduled maintenance" that never goes away means an update was interrupted and left a hidden .maintenance file in the site's root folder. Delete it, reload the site, then rerun the update that was interrupted.

Database connection

For "Error establishing a database connection", check the database name, user, password and host in wp-config.php against your hosting panel, especially after a migration or a password change. If they match, the database server may be down: that is a call to your host.

When only part of the site is broken

Partial failures are easier, because they narrow the search.

  • Only the admin is blank. The admin loads more code than the front end and uses a different memory limit. Look for memory errors in the debug log, and suspect plugins that add admin pages: page builders, SEO suites, analytics dashboards. Raising WP_MAX_MEMORY_LIMIT (the admin's ceiling) may help, within the host's PHP limit.
  • Only the front end is blank. The theme becomes a stronger suspect, along with caching. Clear the caching plugin, the server cache and the CDN before anything else: you may be looking at a stored copy of an error that has already gone.
  • Only one page or one action fails. A checkout that returns 500, or a page with a specific block or shortcode that goes blank, usually points to the plugin that powers that feature. Reproduce the failure with the debug log on and the log line will name it.
  • Only logged-in users see the error, or only you. Try a private window and another browser. If the error disappears, the cause may be a browser extension, a stale cookie, or a cache layer that serves logged-out visitors a working copy.

When to restore a backup or call your host

Fixing the cause is usually better than restoring, because a restore throws away everything since the backup: new orders, comments, form entries, edits. But some situations call for it.

Restore a backup when:

  • You cannot find the cause within half an hour or so, and the site earns money every hour it is down.
  • Several things broke at once, for example after a large batch of updates or a failed migration.
  • A plugin ran a database update that you cannot undo.
  • You find signs of a hack: unfamiliar files, code you didn't add at the top of PHP files, new admin users. In that case, restore from a backup taken before the infection, change every password, and update everything.

On a store, export recent orders before restoring, or restore only the files and keep the current database if the problem was clearly in the code.

Call your host when:

  • The server error log mentions resource limits, killed processes, or timeouts you cannot change.
  • You see 502, 503 or 504 errors that continue after plugins are ruled out.
  • The database server is unreachable.
  • You cannot access the files at all.

When you contact support, give them the exact time of the error, the URL, what you have already tried, and the relevant log lines. A specific report gets a faster, better answer than "my site is down".

Preventing the next one

Most white screens trace back to a change, so the prevention is the routine the rest of this series describes:

  • Test big changes on staging first: major updates, new plugins that touch checkout or layout, PHP upgrades.
  • Keep daily backups stored off the server, and test a restore now and then.
  • Keep the admin email current so Recovery Mode emails reach someone who reads them.
  • Keep a default theme installed as a fallback, and keep customisations in a child theme.
  • Remove unused and abandoned plugins. Fewer plugins means fewer conflicts.
  • Turn on uptime monitoring. A free monitor that checks the site every few minutes and emails you means you hear about a 500 error from a robot, not a customer.
  • Log your changes. When something breaks, "what changed?" is the first question, and a log answers it in seconds.

Troubleshooting checklist

Keep this somewhere you can find it when the site is down.

  1. Note what you see (critical error, blank page, 500, other code) and where (whole site, admin, one page).
  2. Ask what changed recently, and check the host's status page.
  3. Look for the Recovery Mode email; if it is there, use the link and deactivate the named plugin or theme.
  4. No email? Turn on WP_DEBUG_LOG, reload, and read the last fatal error in wp-content/debug.log.
  5. 500 error with nothing in the debug log? Check the server error log, then rename .htaccess.
  6. Deactivate the plugin named in the error, or all plugins by renaming the folder.
  7. Still broken? Rename the active theme's folder to fall back to a default theme.
  8. Memory errors: raise WP_MEMORY_LIMIT within the host's limit, and find out which plugin is so hungry.
  9. After a PHP upgrade: switch back, then update or replace the outdated code.
  10. Still stuck after 30 minutes on a business-critical site? Restore the backup or call the host.
  11. Afterwards: turn debugging off, delete debug.log, clear caches, and log what happened.

The tools change from case to case, but the method doesn't: don't guess, find the error message first. Nine times out of ten, the message tells you exactly where to look.

Sources

Changed