A WordPress update went wrong: a runbook

This runbook is for the minutes after an update to WordPress, a plugin or a theme leaves the site broken, half-working or stuck. Work from the top. The first thing to do is stop: run no more updates, and copy down exactly what the screen says.

In the first few minutes

Find out what happened

The three kinds of update fail in different ways.

• WordPress itself. A warning that the update failed, a blank white page, or a PHP error message. WordPress's documentation names a connection that dropped during the update and wrong file permissions among the causes.
• A plugin. Every page says "There has been a critical error on this website." Or the site loads and the one thing that plugin does has stopped: a form, a gallery, the checkout.
• A theme. Pages load and look wrong, or changes you made in the theme's own files are gone. An update replaces those files, and edits made inside them go with the old version.

Then match what you copied down.

• The maintenance notice. The update was cut short. When the notice goes, the site may show a different fault, because the update did not finish.
• A critical error or a blank page. The email names the plugin or theme. Without the email, the error log does: the white screen of death page shows how to switch the log on, and the error decoder explains a line you paste into it.
• The site loads and something is off. Suspect the last thing you updated. If several updates ran together, find the plugin conflict by switching plugins off in halves.

Bring it back

Work down this list. Skip a route that does not apply.

Clear a stuck maintenance notice. During an update WordPress places a file named .maintenance in the folder that holds wp-admin. Deleting that one file ends the notice at once. The steps are on the page for "Briefly unavailable for scheduled maintenance". Run the interrupted update again afterwards, in case it did not finish.

Get back into the dashboard. The link in WordPress's email opens the login page in recovery mode. The failing plugin or theme is paused for you alone, so the dashboard loads. Visitors still see the error until you deactivate that plugin, or switch theme, and leave recovery mode with the button in the admin bar.

With no email, switch the plugin off from outside. Over SFTP or in your host's file manager, open wp-content/plugins and rename the folder of the plugin you updated. WordPress can no longer find it, so it stops running, and its settings are kept. If you do not know which plugin it was, WordPress's documentation gives the same method for all of them: rename the whole plugins folder to plugins.hold, log in, then rename it back. With WP-CLI, the two extra options stop the broken code from loading:

Go back one version, or restore the backup. With the site reachable again, choose between the two.

• Go back one version when you know which update did it and the rest of the site is sound. Only that plugin's or theme's files change. Nothing that visitors sent is lost. How to safely update WordPress shows how to install the earlier version.
• Restore the backup when you cannot tell which update did it, when several things broke together, or when going back one version did not help. The cost is everything that arrived since the backup. On a store, export the newer orders first.

Repair WordPress itself. If the failed update was WordPress's own, repair forward: WordPress's documentation says going back to an older release is usually not recommended, because newer versions often carry security fixes. Go to Dashboard, then Updates, and run the update again, or re-install the current version from there. A core update copies WordPress's own files over the old ones and keeps files that are not part of WordPress. This WP-CLI command compares WordPress's files, but nothing inside wp-content, with the checksums WordPress.org publishes:

Who to tell

• Your host, if the update stopped with an error about permissions or a connection, or if you have no backup of your own. Ask whether they hold a copy from before the update.
• The author of the plugin or theme. Send both version numbers and the error line, so the fault gets fixed for everyone.
• Anyone else who edits the site. Ask them to stop until this is settled. Work saved between a backup and a restore is lost.
• Customers, only if something they rely on was affected. Check for orders and messages that arrived during the fault and answer them.

Afterwards

• Stay on the older version only until a fixed one is released. Security fixes arrive in new versions.
• Try the update again on a copy first. Set up a staging site, apply the same update there, and look for the fault before the live site is touched.
• Keep a note of both version numbers, the error line, what brought the site back and how long it took.

On a care plan, our update service applies updates weekly, looks at the site afterwards and undoes an update that went wrong.

When to hand it over

• The error log points at WordPress's own files, not at a plugin or the theme.
• The site is still broken with the updated plugin off and a default theme active.
• There is no backup from before the update.
• It is a store, and orders are arriving while you test.

WP Ministry repairs a site that an update broke as a one-time fix, which begins with a free diagnosis that gives you the cause in writing.