A plugin update broke my WordPress site: how to diagnose and roll back safely

You opened Plugins > Updates in wp-admin, clicked Update Now on a plugin you have run for years, and the page came back broken. The front end shows the critical error screen, or worse, a completely blank document. The dashboard might still load, or it might be gone too. Whatever you did in the last 60 seconds, you want to undo. This article is the calm, step-by-step undo.

What "broke my site" usually means after a plugin update

A plugin update can break a site in three different ways, and the recovery path depends on which one you are in. Identifying the failure mode first saves you from running the wrong fix.

1. PHP fatal error. The plugin update introduces code that PHP refuses to execute. You see "There has been a critical error on this website" on the front end, or a completely blank page if the fatal fires very early. The HTTP response is 500. The full diagnosis path for this screen lives in there has been a critical error on this website.
2. Visual or functional regression. The site loads but the layout is broken, a button no longer works, a form silently fails, or product pages render the wrong template. No PHP error fires, the HTTP status is 200, but something is clearly wrong.
3. Database corruption or schema mismatch. The plugin ran a database migration on update (most commonly WooCommerce on a major version, or any plugin that calls dbDelta()), and now the new code is trying to read tables that look different from before. Symptoms range from missing data to fatals on specific pages.

The first one is the most common and the most visible. The third one is the most dangerous, because the obvious fix (downgrade the plugin files) makes things worse. I will get to that.

Step 1: Check the WordPress Recovery Mode email

If the update produced a PHP fatal during a normal page load, WordPress has already sent you an email. This is the canonical recovery flow, introduced in WordPress 5.2 in May 2019 and documented in the recovery mode handbook.

What to do:

1. Open the inbox of the address tied to your WordPress admin user. Check spam too. The subject line is "[your site name] Your Site is Experiencing a Technical Issue". The body names which plugin caused the fatal and contains a one-time recovery link.
2. Click the recovery link. WordPress logs you into wp-admin in recovery mode, a special session in which the offending plugin is paused for you and only you. Visitors still see the critical error.
3. Go to Plugins. The broken plugin is marked as paused. Deactivate it.
4. Log out. That ends recovery mode.

You will know it worked when the site loads normally for visitors and the fatal screen is gone. Confirm by opening the site in a private browser window.

Two things to know about recovery mode that articles often skip:

• Recovery mode does not work on background requests. It only fires when a regular page load triggers the fatal. Cron jobs and REST API background calls that hit the same fatal will not trigger an email or a recovery session. If your fatal only happens during, say, a scheduled WooCommerce action, the recovery email may never arrive.
• Email delivery is not guaranteed. If the fatal happens before SMTP plugins load, WordPress tries to send the email through PHP's mail() function directly, which on many hosts is unreliable or blocked. The email may land in spam or be silently dropped. If no email arrives within five minutes, move to step 2.

The recovery link is rate-limited: a fresh email is only sent at most once every 24 hours by default. If you missed the first one, do not keep refreshing the broken page hoping for another.

Step 2: Get into the site without the dashboard

When the recovery email never arrives, or wp-admin itself is broken, you need to disable the offending plugin from outside WordPress. There are three reliable ways. Use whichever your host gives you access to.

Option A: rename the plugin folder via SFTP

This is the simplest and safest path. It requires only file access.

1. Connect to your site over SFTP, SSH, or your host's file manager.
2. Navigate to wp-content/plugins/.
3. Rename the suspect plugin's folder by appending .off, for example from bad-plugin to bad-plugin.off.
4. Reload the front end of the site in a private browser window.

You will know it worked when the site loads normally. WordPress could not find the plugin in its expected location, so it treats it as deactivated and continues. The plugin's settings stay in the database. When you eventually fix or replace the plugin and restore the folder name, all your configuration is still there.

If you do not yet know which plugin is the culprit, rename the entire wp-content/plugins/ folder to plugins.disabled. WordPress deactivates every plugin at once. Reload the site. If it recovers, restore the folder name, then re-enable plugins one at a time from wp-admin until the fatal returns. The last plugin you re-enabled is the cause.

Option B: WP-CLI

If your host gives you SSH access and WP-CLI is installed, you have a faster option. The relevant command is documented in the WP-CLI plugin deactivate reference.

# Deactivate one plugin by its folder name
wp plugin deactivate bad-plugin

# Deactivate every plugin at once (fastest emergency stop)
wp plugin deactivate --all

# Deactivate everything except WooCommerce
wp plugin deactivate --all --exclude=woocommerce

# On multisite, deactivate network-wide
wp plugin deactivate bad-plugin --network

WP-CLI talks directly to the WordPress database and the file system, so it works even when wp-admin returns a fatal. You will know it worked when the next wp plugin list shows the plugin as inactive and the front end loads.

Option C: emergency PHP file (do not use unless A and B are impossible)

A few hosts lock down both SFTP and SSH and only let you upload through a web interface. In that case you can drop a one-shot PHP file in the WordPress root that calls deactivate_plugins() for the suspect plugin, then load the file once in your browser, then delete it immediately. This is a last resort. Editing wp_options.active_plugins directly in the database is even further down the list and is genuinely a last resort, because a serialised PHP array is easy to corrupt by hand.

Step 3: Identify the culprit by reading the debug log

Once the site is back up, you still need to know which plugin caused the fatal so you can decide what to do next. The debug log tells you the file and the line, which tells you the plugin.

If WP_DEBUG_LOG is not yet enabled, follow my guide on enabling and reading the WordPress debug log to set the four constants in wp-config.php correctly. The short version is:

// Turn on WordPress debugging
define( 'WP_DEBUG', true );
// Write all PHP errors to wp-content/debug.log
define( 'WP_DEBUG_LOG', true );
// Hide errors from page output (do NOT skip this line)
define( 'WP_DEBUG_DISPLAY', false );
// Belt-and-braces: also tell PHP not to display errors
@ini_set( 'display_errors', 0 );

Once those four lines are in place, temporarily reactivate the broken plugin (rename the folder back from bad-plugin.off to bad-plugin, or run wp plugin activate bad-plugin), reload the page that triggered the fatal, and immediately deactivate the plugin again. Then open wp-content/debug.log. The last entries describe exactly what broke. A typical line looks like:

[08-Apr-2026 14:23:11 UTC] PHP Fatal error: Uncaught Error: Call to undefined function get_field() in /var/www/html/wp-content/plugins/some-plugin/render.php on line 87

The folder name in the path (some-plugin) is the plugin to suspect. The function name in the message (get_field()) often tells you the underlying cause: in this example, the plugin depends on Advanced Custom Fields, which is not loaded. Save the full last 30 lines of debug.log. You will need them when you report the bug to the plugin author and when you decide which rollback path to take.

Set WP_DEBUG back to false once you have your answer. Live sites should never run with debug logging on for longer than the incident itself.

Step 4: Roll back the plugin

You have three rollback options, and they are not equivalent. Choose based on what the plugin actually does to your database when it updates.

Option A: use the WP Rollback plugin (free, wordpress.org plugins only)

The WP Rollback plugin at version 3.1.0 is the standard tool for going back to an older version of a plugin without a full backup restore. After installation, every plugin in your dashboard gets a "Rollback" link that lets you pick any previous version from the WordPress.org SVN repository and reinstall it the same way the built-in updater installs new versions.

The free version only works with plugins hosted on wordpress.org. Premium plugins, paid extensions, and anything you got from a developer's own site or marketplace will not show a rollback link unless you are running WP Rollback Pro from wprollback.com, which uses a separate Plugin Vault archive.

How to use it for a wordpress.org plugin:

1. Install WP Rollback from the WordPress plugin directory and activate it.
2. Go to Plugins > Installed Plugins.
3. Find the broken plugin. Below it is a new "Rollback" link.
4. Click it. You see a list of every released version of the plugin.
5. Pick the version that worked before the bad update. Click "Rollback".
6. Wait for the install to finish.
7. Reload the front end and test the previously broken page.

You will know it worked when the site loads normally and the page that triggered the fatal now responds correctly.

A historical detail worth knowing: WP Rollback versions before 3.0.12 had a bug where the rollback flow accidentally fired the plugin's uninstall.php hook, which on plugins that delete their data on uninstall would wipe out database tables and options before reinstalling the older code. That bug was fixed in 3.0.12 in 2024 and never occurs on current versions. If you are about to install WP Rollback for the first time, you are getting 3.1.0 or newer and you will not hit it. If you have an old version of WP Rollback already installed, update it first.

Option B: restore from a full backup (the only safe path for migration-heavy plugins)

This is the option that catches the trap WP Rollback cannot solve.

WP Rollback only replaces files. It does not revert your database. That matters more than it sounds.

When a plugin runs a database migration on update, the new version writes new tables, new columns, or new schemas, and stores a version number in wp_options so it knows the migration ran. WooCommerce does this on every major version (8.x to 9.x changed the order tables, for example). Gravity Forms does it. Any plugin that calls dbDelta() on activation potentially does it.

If you roll back the files of one of these plugins without rolling back the database, the old code loads against a database it does not understand. The result is the same fatal you were trying to fix, plus possibly silent data corruption that you may not notice for days.

The safe path for any migration-heavy plugin is to restore the entire site, files and database, from a backup taken before the update.

If your host or your backup tool can do a one-click full restore, use it. If you have separate file and database backups, restore them as a pair. The match between files and database is what matters. A file restore from yesterday paired with a database from last week is its own broken state. The full mechanics of the restore live in how to restore WordPress from a backup, and the question of which backup to restore from belongs in the same article.

You will know it worked when the site loads, the previously broken page responds correctly, and a quick scan of recent posts, orders, or form submissions shows no missing data after the restore point.

Option C: manually reinstall the previous version

For premium plugins and anything that is not on wordpress.org, this is often the only file-only rollback option short of WP Rollback Pro.

1. From your account on the plugin vendor's site, download the previous version's .zip file. Most reputable vendors keep an archive of historical versions in your account area. If they do not, contact support and ask.
2. In wp-admin, go to Plugins > Installed Plugins.
3. Deactivate the broken plugin and delete it. WordPress asks if you want to delete the plugin's data. Choose no, unless you want to start fresh, because most plugins call their uninstall.php hook here, which on some plugins deletes all your settings.
4. Click Add New > Upload Plugin and upload the older .zip file.
5. Activate the older version.
6. Reload the front end and test.

If the plugin ran a database migration on the bad update, this method has the same trap as Option A: the database is in the new schema and the old code may not handle it. For any plugin that touches its own tables on update, full backup restore (Option B) is the safer choice.

A note on what WordPress core's "rollback" features actually do

You may have read that WordPress 6.3 or WordPress 6.6 added rollback features to core. Both did, but neither one is the user-clickable rollback button people think they are.

WordPress 6.3 added auto-revert for failed manual updates in August 2023. Before a manual plugin update begins, WordPress moves the previous version to wp-content/upgrade-temp-backup/. If the update process itself fails partway through (the download is corrupt, the destination folder cannot be cleared, the install package returns an error), WordPress automatically swaps the old version back. It does not give you a rollback button after a successful update. If the update completed but the new version is broken, WP 6.3 does nothing for you. The upgrade-temp-backup/ directory is documented as not being for manual rollback use.

WordPress 6.6 added auto-rollback for auto-updates in July 2024. After a background auto-update completes, WordPress fires a loopback HTTP request to its own homepage. If that request hits a PHP fatal error, WordPress reverts the plugin to its previous version automatically and emails the admin. This only applies to background auto-updates, not to manual ones triggered from the dashboard. It only catches PHP fatals, not visual breakage, JavaScript errors, or data corruption. And because it depends on loopback requests, sites with broken loopbacks may revert updates unnecessarily, or fail to revert updates that should have been reverted.

The takeaway: when you click "Update Now" from the Plugins screen and the new version is broken, neither feature helps you. Recovery falls to you, which is the entire reason this article exists.

When to escalate

If none of the above brings the site back, or if the rollback succeeded but data is missing, hand the problem to your host or a WordPress specialist. Every minute they save on context is a minute closer to the site being healthy again. Collect this bundle before you ask:

• The exact name and version of the plugin you updated, plus the version you updated from if you remember.
• A copy of the front-end error message visitors see, or "blank page" if there is none.
• The HTTP status code (open the browser's Network tab on the failing request).
• The PHP version on the server (visible in your hosting panel).
• The WordPress version (from wp-includes/version.php or any working dashboard view).
• The full last 30 lines of wp-content/debug.log after triggering the fatal once.
• A list of every recovery step you tried, in order, and what happened each time.
• Whether you have a backup from before the update, where it is stored, and how to restore it.
• For migration-heavy plugins (WooCommerce, Gravity Forms, anything with custom tables), whether the broken update went through dbDelta() or installed a new schema version.

A specialist can usually resolve a plugin-update incident within an hour with that bundle in hand. Without it, the same job takes most of an afternoon.

Reporting the bug to the plugin author

After you have rolled back and the site is up, do not skip this step. Plugin authors fix bugs they hear about. The bug reports they need are short, specific, and include the failing line from the debug log.

For a wordpress.org plugin, open a thread in the plugin's support forum on wordpress.org (each plugin has a "Support" tab on its directory page). Include:

• The plugin version that broke (the new one).
• The plugin version that worked (the previous one).
• Your PHP version and WordPress version.
• The full last PHP Fatal error line from debug.log, copied verbatim.
• Any other plugins active at the time, especially anything the failing line hints at depending on.
• The steps to reproduce, if you can identify them. Sometimes "I clicked update" is the only step there is.

For a premium plugin, file a support ticket through the vendor's account area with the same bundle. Premium support tickets are often faster than wordpress.org forum threads, which is part of what you are paying for.

Safer update practices, so the next one does not break the site

You cannot eliminate plugin update failures, but you can keep them rare and survivable.

• Test plugin updates on a staging copy first. A staging environment is the single biggest risk reducer for this incident type. The full setup path lives in setting up a WordPress staging environment. Important nuance: staging is not perfect. Staging sites can differ from production in PHP version, server config, traffic patterns, database size, and third-party service connections. A plugin conflict that only appears under production load will not show up on a quiet staging copy. Staging reduces risk; it does not eliminate it.
• Take a full backup immediately before every update. Files and database, not just one. A backup taken five minutes before the update lets you restore in 60 seconds. A backup from yesterday means losing today's content. If your host does this automatically, confirm where the backups land and how you trigger a restore.
• Update one plugin at a time. Updating ten plugins in a single click saves you 30 seconds and costs you the ability to know which one broke things if anything goes wrong. Updating one at a time, then reloading the front end after each, is slower and safer.
• Watch the site for five minutes after every update. Many plugin failures only show up on the first request that uses the changed code path. A 200 on the homepage right after the update does not prove the checkout still works. Click through the parts of the site that matter for your business.
• Disable auto-updates for plugins that have hurt you before. WordPress auto-updates are off by default for plugins, but you may have enabled them. If a plugin has previously broken your site on update, manually controlling its updates is worth the small extra effort.
• Subscribe to the plugin's release notes. For mission-critical plugins (especially WooCommerce, anything that handles payments, anything that handles customer data), reading the changelog before you click update tells you whether the new version touches the database. If it does, you treat that update as a major change, not a routine click.

The reason plugin updates break sites is that WordPress is an open ecosystem with tens of thousands of plugins built by people with different testing standards. The reason you can recover quickly is that you have a recovery flow you have practised once, before you needed it. Run through this article on a staging site you can break on purpose. The next real incident becomes a fifteen-minute job instead of a panicked afternoon.