Plugin Update Broke WordPress? Recovery Mode, WP-CLI and Rollback

This article is a localized edition of the Japanese original. Read the Japanese original

Right after you update a plugin, the screen may go blank, show "There has been a critical error on this website.", or lock you out of the admin. Most of the time the updated plugin's code is throwing a PHP error, or it no longer works with another plugin, your theme or your PHP version.

This article explains how to get the site displaying again, confirm the cause and roll back to the version you had before the update. The WP-CLI commands were tested on WordPress 7.1.4 with the WP-CLI Docker image (as of November 2026).

First: identify the plugin that caused it

When a fatal error occurs, WordPress sends an email with the subject "[Site Name] Your Site is Experiencing a Technical Issue" to the admin email address. It names the plugin that caused the error, describes the error and includes a link to enter recovery mode.

• It goes to the Administration Email Address under Settings → General. If you define RECOVERY_MODE_EMAIL in wp-config.php, it goes there instead.
• By default the email is sent at most once a day. The link is also valid for one day by default.
• If no email arrives, check your server's mail settings and your spam folder, and look for the cause in the error log described below.

If you updated only one plugin just before the problem, it's the prime suspect. If you updated several at once, pin it down from the email or the error log.

Method 1: Enter the admin in recovery mode and deactivate it

1. Open the recovery mode link in the email and log in with an administrator account.
2. Open the Plugins screen. The plugin that caused the error is flagged there. In recovery mode, that plugin is paused only in your browser.
3. Deactivate the plugin that caused the problem.
4. Click "Exit Recovery Mode" at the top of the screen to return to normal.

Recovery mode only applies to the browser that opened the link. Ordinary visitors keep seeing the error screen until you deactivate the plugin.

Method 2: Stop it by renaming the plugin folder

If the email never arrived or the link has expired, rename the plugin's folder over FTP/SFTP or with your hosting provider's file manager.

wp-content/plugins/example-plugin      ← the plugin causing the error
wp-content/plugins/example-plugin.off  ← rename it

When WordPress can't find an active plugin's files, it starts without loading that plugin. Once you can get into the admin, open the Plugins screen first. It reports that the missing plugin was deactivated due to an error, and it is now treated as inactive. Then rename the folder back and leave the plugin deactivated until a fixed version comes out.

If you don't know which plugin is responsible, renaming the wp-content/plugins folder itself stops every plugin. When the site comes back, restore the name and activate plugins one at a time to find the cause.

Method 3: Deactivate it with WP-CLI

If you can log in over SSH and WP-CLI is available, you can deactivate it with a command. Run it in the site's directory (where wp-config.php lives).

# Check the status (with a broken plugin, this may also fail with the error)
wp plugin list --fields=name,status,version

# List plugins without loading them
wp plugin list --fields=name,status,version --skip-plugins

# Deactivate the plugin causing the problem
wp plugin deactivate example-plugin --skip-plugins

When a plugin is broken, WP-CLI loads it too and stops with the same error. --skip-plugins boots WordPress without loading plugins, so you can still deactivate it. If the theme is the cause, add --skip-themes as well.

Check what the error says

To confirm the cause or report it to the developer, look at the error log. Add the following three lines to wp-config.php above the "That's all, stop editing!" line (if there is already a WP_DEBUG line, change it).

<?php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

With these settings, errors are not shown on screen but are written to wp-content/debug.log. Setting WP_DEBUG_DISPLAY to true exposes error details to visitors too, so keep it false on a live site. Once you've found the cause, set WP_DEBUG back to false and delete debug.log. For details, see How to enable WordPress debug mode.

These are errors you'll often see in the log:

If the PHP version is the problem, compare the "Requires PHP" value on the plugin's page with your server's PHP version.

Roll back to the previous version

While the plugin is deactivated, you lose its features. Until a fix is released, you can go back to the version you had before the update.

Plugins distributed on wordpress.org

You can reinstall a specific version with WP-CLI. --force overwrites the installed version.

# Example: go back to 1.6.5
wp plugin install example-plugin --version=1.6.5 --force
wp plugin activate example-plugin

# Stop auto-updates for this plugin until a fixed version is out
wp plugin auto-updates disable example-plugin

If you can't use WP-CLI, open "Advanced View" on the plugin's wordpress.org page and download an older ZIP from "Previous Versions" near the bottom. Unzip it and replace the folder in wp-content/plugins/ over SFTP. You can stop auto-updates with "Disable auto-updates" on the Plugins screen.

As wordpress.org itself warns, older versions may still contain vulnerabilities that have since been fixed. Treat a rollback as a stopgap until a fix is released, and check the changelog for security fixes.

Paid plugins

Paid plugins aren't on wordpress.org, so the commands above won't work. Check whether the vendor offers older versions on your account page, or ask their support.

Watch out for database changes

Some plugins convert their database tables or settings to a new format during an update. In that case, rolling back only the files may not work correctly. If problems persist on the old version, restore from the backup you took before the update (both files and database).

What WordPress’s built-in protections cover

WordPress has mechanisms for failed updates, but they don't prevent every case.

If you update manually and the update itself succeeds but the site breaks, nothing is rolled back automatically. Use the steps in this article.

Preventing it from happening again

• Back up before updating. Keep both files and the database in a form you can restore.
• Update one plugin at a time. Updating several at once makes it hard to tell which one caused the problem.
• Read the changelog. Be especially careful with major version jumps (for example, 2.x to 3.x) and updates that raise PHP or WordPress requirements.
• Try it on staging first. Update on a test site with the same setup as production, check the main pages and features, then apply it to production.
• Choose what gets auto-updated. You can turn off auto-updates for plugins your site depends on and update them manually, leaving only low-impact plugins on auto.

Summary

• Identify the plugin that caused the error from the admin email or debug.log
• Stop it with the recovery mode link, by renaming its folder, or with wp plugin deactivate --skip-plugins
• For wordpress.org plugins, roll back with wp plugin install slug --version=x.y.z --force, and keep the old version only as a stopgap
• Some updates change the database, so have a backup from before the update
• Problems caused by a manual update are not rolled back automatically

For checks that apply to blank-screen problems in general, see also How to use WordPress recovery mode.

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)