Recovering a WordPress site broken by an update

A WordPress update that breaks your site is stressful, but it's also one of the most common and recoverable problems. You might see a blank white screen, a "critical error" message, a broken layout or be unable to reach the dashboard at all.

Updates cause problems when a new version of a plugin, theme or WordPress itself clashes with something else on your site. That might be two plugins that no longer work together, a theme that hasn't kept up with WordPress or a plugin that needs a newer version of PHP than your server runs.

WordPress has several recovery features built in, and in most cases you can fix the problem without losing any data.

Check for a recovery mode email

Since WordPress 5.2, when a plugin or theme causes a fatal error, WordPress emails the site administrator a special link that opens the dashboard in "recovery mode".¹ The subject is "[Your site name] Your Site is Experiencing a Technical Issue".²

Follow the link, log in and deactivate the plugin or theme named in the email (usually the one you just updated). The rest of the site should come back while you look into it. Our guide to the WordPress critical error covers recovery mode and debugging in more detail.

If you didn't get the email, check your spam folder. It goes to the administration email address under Settings → General, which may not be the address you use day to day. WordPress only sends one of these emails a day,³ so an earlier email may have covered the same problem. And if your host blocks WordPress from sending email, it may not have been sent at all. In that case, move on to the steps below.

Check for a stuck maintenance message

If your site shows "Briefly unavailable for scheduled maintenance. Check back in a minute.", the update started but may not have finished cleanly. WordPress normally clears this itself, and it stops treating the site as in maintenance 10 minutes after the update began.⁴ If the message is still showing after that, it's usually being served from a cache or by a plugin. Our guide to getting WordPress out of maintenance mode covers this in detail, including deleting the leftover .maintenance file.

Deactivate the plugin or theme that was updated

If you know which plugin or theme was updated before the problem started, deactivate that one first. If several things updated at once, you'll need to test them one at a time.

If you can reach the dashboard, deactivate plugins under Plugins → Installed Plugins and check the site after each. Deactivating plugins switches their features off for visitors too (including shops, forms and security), so do this at a quiet time or on a staging copy if you can.

If you're locked out of the dashboard, connect via SFTP or your hosting file manager, go to wp-content/plugins/ and rename the plugin's folder (for example, from plugin-name to plugin-name-disabled). WordPress can't load a plugin whose folder has been renamed. Rename it back once you've fixed or rolled back the plugin, then check it's active again under Plugins.

To test whether your theme is the problem, rename your active theme's folder inside wp-content/themes/. WordPress then switches to its default theme, if one is installed.⁵ This is a real theme change that visitors will see. When you've finished, rename the folder back, reactivate your theme under Appearance → Themes and check your menus and widgets are still in place.

Turn on debug logging

If you still can't find the cause, WordPress's debug log can show you the exact error.

Open wp-config.php via SFTP or your hosting file manager, downloading a copy first so you can put it back if anything goes wrong. Add these lines just above the comment that reads /* That's all, stop editing! */:⁶

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

Reload the page that was showing the error, then look in wp-content/debug.log. Fatal errors include a file path and line number, which usually points straight at the plugin, theme or file responsible.

When you've finished, remove these lines (or set WP_DEBUG to false) and delete debug.log. The log can reveal details about your site and server, and on many servers files in wp-content can be viewed by anyone who knows the address.

Roll back the update

Once you know which update caused the problem, you can go back to the previous version while you wait for a fix. Take a backup first, since you'll be overwriting the plugin, theme or WordPress files.

Be careful if the update was a security fix. Rolling back puts the security problem back on your site, so treat it as a short-term measure. Our guide to handling a plugin security vulnerability explains how to judge the risk. If the plugin is no longer maintained at all, see our guide to dealing with closed or abandoned plugins.

Plugins. For free plugins from WordPress.org, the plugin's page has an Advanced View link where older versions can be downloaded. Download the version that was working, then either upload it through Plugins → Add New Plugin → Upload Plugin (WordPress will offer to replace the current version) or upload its folder via SFTP to wp-content/plugins/. For premium plugins, older versions are usually in your account on the developer's website.

Themes. Re-upload the previous version from your own copy or from where you bought it. If you don't have one, your host's backups may.

WordPress itself. Rolling back WordPress core is more involved and riskier, because updates can also change your database. Restoring a full backup from before the update is usually safer. If you do need to roll back core, older versions are on the WordPress releases page,⁷ but this is a job for your host or a developer if you're not confident.

WordPress has some rollback protection of its own. Since version 6.3, if a manual plugin or theme update fails to install, WordPress restores the previous version,⁸ and since version 6.6 it tries to roll back automatic plugin updates that cause a fatal error.⁹ These are safety nets rather than guarantees, so backups are still essential.

Restore from a backup

If you have a backup from before the update, restoring it is often the simplest and safest way back. Most hosts offer automatic backups you can restore from their control panel. If you use a backup plugin, you may need SFTP or database access to restore it when the dashboard isn't working, depending on the plugin.

Restoring a backup replaces your site with the version from when the backup was taken, so anything added since (new orders, form entries, comments or posts) may be lost. On a shop, check with your host or developer before restoring the database.

After restoring, hold off on applying the same update again until a newer release fixes the problem, or test it on a staging copy first.

Test future updates on staging

Many hosts offer staging sites: a private copy of your site where you can apply updates and check for problems before touching the live site. This is the most reliable way to avoid update-related outages.

If your host doesn't offer staging, a local copy of your site on your own computer does a similar job. Even a quick check on a copy catches the most obvious conflicts before they reach your visitors.

Need help recovering your site?

If you can't find the problem, don't have a backup or aren't comfortable editing files on your server, my freelance WordPress development and emergency WordPress support can help get your site running again. Your hosting provider may also be able to restore a backup for you.