CompatNav

A WordPress plugin update broke the site: what to do, in order

By CompatNav · Published · Last reviewed · 2 min read

Short answer

First get the site back, then find the cause. If WordPress emailed a recovery-mode link, use it to log in and deactivate the plugin. If you can’t log in, rename the plugin’s folder in wp-content/plugins/ with your host’s File Manager or FTP: WordPress deactivates it. Then roll back to the previous version, or restore the backup. Only when the site is back, read the error message, tell the plugin’s developer, and decide whether to wait for a fix or replace the plugin.

Step 1: get the site back

  1. Check the administrator’s inbox. Since WordPress 5.2, when a plugin causes a fatal error, WordPress shows a message instead of a blank page and emails the administrator a link to recovery mode (make.wordpress.org). Log in through that link and deactivate the plugin named in the email.
  2. No email, or no access? Open your host’s File Manager (or FTP), go to wp-content/plugins/ and rename the plugin’s folder, for example slider to slider-off. WordPress can’t find it any more and deactivates it.
  3. Several plugins updated at once? Rename the plugins folder itself to find out whether one of them is the cause, then rename it back and deactivate them one by one in the dashboard.

Visitors see the site again as soon as the broken plugin is off. Whatever it did is missing until it’s back, so for a shop or booking plugin, move fast to step 2.

Step 2: roll back

  • Install the previous version. For plugins from wordpress.org, earlier versions are on the plugin’s page under Advanced View; with WP-CLI, wp plugin install <name> --version=<x> --force, the same command we used to set up the test in WP-CLI: update plugins safely.
  • Or restore the backup from before the update. A full restore can lose orders and form entries made since, so roll back the plugin alone when you can.

Step 3: find the cause

The error message says what went wrong, and where: the path after wp-content/plugins/ names the plugin, and the file and line are for its developer. It’s in WordPress’s email, in your host’s error log, or in the WordPress debug log. Three causes cover most cases:

  • A requirement the server doesn’t meet, often a newer PHP version than the site runs. The plugin’s page on wordpress.org lists its “Requires PHP”.
  • A conflict with another plugin or the theme. The plugin conflict test finds which.
  • A bug in the new release. Check the plugin’s support forum: others are probably reporting the same thing.

Step 4: tell the developer, then decide

Send the plugin’s developer the exact message, the plugin’s old and new version, WordPress and PHP versions. Then decide: wait for a fixed release on the old version, or replace the plugin if it breaks often.

Next time

  1. A tested backup before every update day.
  2. Important plugins updated one at a time, with the site opened in between.
  3. Big updates tried on a staging copy first.
  4. Auto-updates only for low-risk plugins: on or off for client sites?

Key takeaways

  • Site first: recovery-mode link from WordPress’s email, or rename the plugin folder to deactivate it.
  • Roll back: install the previous version of the plugin, or restore the backup from before the update.
  • The error message in the email or log names the plugin, the file and the line.
  • Tell the plugin’s developer with the exact message and versions; wait for a fixed release.
  • Next time: backup, update important plugins one by one, staging for big updates.

Frequently asked questions

Will I lose content if I restore a backup?

Anything created after the backup (orders, comments, form entries) can be lost with a full restore. Rolling back only the plugin keeps your data; that’s why it comes first.

The plugin worked yesterday. Why did the update break it?

Usually a conflict with another plugin or the theme, a requirement the server doesn’t meet (such as a newer PHP version), or a bug in the new release. The error message tells you which.

How do I install an older version of a plugin?

For plugins from wordpress.org, the plugin’s page has older versions under Advanced View, and WP-CLI can install one with wp plugin install <name> --version=<x> --force. For premium plugins, ask the seller.

Check your own site before you upgrade

CompatNav is a free WordPress plugin. It reads the code of your plugins and themes on your own server and tells you, in plain words, what will break and what will only show notices on the PHP version you choose. It never changes your code. It can’t see problems that only appear while code runs with real data, so a quick check of your site after the upgrade still matters.

Get CompatNav on wordpress.org How it works

Sources

About the code examples: each output is the real output of the code shown, run with the official PHP builds, without a php.ini, with all errors reported and displayed. Only the file path was replaced by a neutral server path.