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 issues you'll encounter. You might see a blank white screen, a fatal error message, a broken layout or be unable to access the admin dashboard at all.

Updates cause problems when a new version of a plugin, theme or WordPress core introduces a change that conflicts with something else on your site. This might be a deprecated PHP function, an incompatibility between two plugins, a theme that hasn't been updated to match the latest WordPress version or a plugin that requires a newer version of PHP than your server is running.

The good news is that WordPress has built-in recovery features, and in most cases you can fix the problem without losing any data.

Check for a recovery mode email

Since WordPress 5.2, fatal errors that occur during or after an update trigger an automatic recovery mode email to the site administrator. The subject line is typically "Your Site is Experiencing a Technical Issue" and the email contains a special login link that bypasses the normal dashboard.

Follow the link, log in and deactivate the plugin or theme that was updated immediately before the error appeared. This should restore your site while you investigate further.

If you didn't receive the email, check your spam folder. The email is sent to the admin email address configured under Settings → General, which may not be the same as your personal email. If your hosting environment restricts the PHP mail() function, the email may not have been sent at all. In that case, move on to the manual steps below.

Remove the .maintenance file

If your site displays the message "Briefly unavailable for scheduled maintenance. Check back in a minute," the update process started but didn't finish cleanly. WordPress creates a temporary .maintenance file in the root directory during updates and removes it when the process completes. If the update was interrupted (by a timeout, a server error or closing the browser too early), this file gets left behind and keeps your site in maintenance mode.

Connect to your site via FTP, SFTP or your hosting file manager, find the .maintenance file in the WordPress root directory and delete it. Your site should come back immediately. If it doesn't, the update may have failed partway through, and you'll need to work through the remaining steps below.

Deactivate plugins and switch themes

If you know which plugin or theme was updated before the problem started, try deactivating that one first. If you're not sure, or if several things updated at once, you'll need to test them individually.

If you can still access the WordPress dashboard, go to Plugins → Installed Plugins and deactivate all plugins. If the site recovers, reactivate them one at a time, checking the site after each one to identify which plugin is causing the conflict.

If you're locked out of the dashboard, connect via FTP or your hosting file manager and navigate to wp-content/plugins/. Rename each plugin folder one at a time (for example, change plugin-name to plugin-name-disabled) and check whether the site recovers after each one.

To test whether a theme is the problem, rename your active theme's folder inside wp-content/themes/. WordPress will fall back to a default theme if one is installed. If the site loads correctly with a default theme, the issue is in your theme.

Enable debug mode

If deactivating plugins and switching themes hasn't revealed the cause, enabling WordPress debug mode can help you find the exact error.

Open wp-config.php via FTP or your hosting file manager and add the following 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);

Reload the page that was showing the error, then check wp-content/debug.log. Fatal errors will reference a specific file path and line number, which usually points directly to the plugin, theme or core file responsible.

Once you've identified the error, disable debug mode by removing these lines or setting WP_DEBUG to false. Leaving debug mode enabled on a live site is a security risk, as the log can contain sensitive information about your server environment.

Roll back the problematic update

Once you've identified which update caused the problem, you can roll it back to the previous version while you wait for a fix.

For plugins, visit the plugin's page on wordpress.org and look for a "Previous Versions" or "Advanced View" section where older versions are available for download. Download the version that was working before, then upload it via FTP to wp-content/plugins/, overwriting the current version.

For themes, re-upload the previous version from your own local copy or from the marketplace where you purchased it. If you don't have a copy of the previous version, check whether your hosting provider's backup system has one.

For WordPress core, download the specific older release from wordpress.org/releases and upload the files via FTP, overwriting the existing core files. Do not overwrite your wp-content folder or wp-config.php file, as these contain your site's content and configuration. Core rollbacks are more involved and carry more risk, so consider restoring from a full backup instead if you have one available.

Restore from a backup

If you have a recent backup from before the update, restoring it is often the simplest and safest path to recovery. Most hosting providers offer automatic backups that you can restore from their control panel. If you use a backup solution configured within WordPress, you may need FTP or database access to trigger the restore, depending on the tool.

After restoring, hold off on applying the same update again until you've confirmed that the issue has been resolved in a newer release, or test the update on a staging environment first.

Test future updates on staging

Many hosting providers offer staging environments where you can clone your live site, apply updates and check for problems before pushing changes to production. This is the most reliable way to prevent update-related outages on a live site.

If your host doesn't offer staging, consider setting up a local development copy of your site for testing. Even a quick check on a copy can catch the most obvious conflicts before they affect your visitors.

Need help recovering your site?

If you can't identify the problem, don't have a backup to restore from or aren't comfortable editing files on your server, my emergency WordPress support service can help get your site running again.