WordPress Plugin Update Failed - Complete Fix

You click update on a plugin. The dashboard shows a little spinner. Then it stops spinning and says "Update failed."

You go to Plugins and the plugin is now inactive. You click "Activate" and get a fatal PHP error. Your admin is broken. Your site's frontend is broken. You're stuck between an old version that worked and a new version that didn't install.

This happened to us last month. A plugin updated, something went wrong during extraction, and the plugin was left in a half-installed state. The plugin files were partially replaced. The database migration didn't run. Neither version worked.

It took us 20 minutes to roll back and recover. It should have taken 5. We didn't know the right steps. Now we do.

Why Plugin Updates Fail

A plugin update is a sequence of steps:

  1. Download the update .zip file from wordpress.org (or the plugin developer's server)
  2. Extract the .zip file to wp-content/upgrade/
  3. Backup the old plugin folder
  4. Move the new files to wp-content/plugins/
  5. Run any database migrations (if the update needs them)
  6. Delete the temporary upgrade folder

If any step fails, the update stops and the plugin is left partially updated.

Common reasons updates fail:

  • Download failure: The plugin server is down or slow. The .zip file download times out before finishing.
  • Extraction failure: The .zip is corrupted. Or your server can't unzip it (php-zip extension missing).
  • File permission error: WordPress can't write to wp-content/plugins/pluginname/. Permissions are too restrictive.
  • Disk space full: Not enough free space to extract the new files. Update aborts midway.
  • Memory limit: The plugin is large. PHP runs out of memory during extraction.
  • PHP version incompatible: The new plugin version requires PHP 8.0+ but your server runs 7.4. Update extracts but fails activation.
  • Conflicting plugin: Another active plugin hooks into the update process and throws an error.
  • Database migration failed: The update tried to alter the database and failed. This is the sneakiest failure—the files update fine but the plugin won't activate because the database is wrong.
  • Server timeout: The update took longer than max_execution_time. PHP killed the process mid-update.

Step 1: Diagnose the Failure

Check what the error message says

The error message often tells you exactly what failed. Common ones:

  • "Could not create directory" — File permission issue
  • "Unable to locate WordPress Content directory" — Plugin lost track of the install. Usually a memory issue.
  • "Destination folder already exists" — Old plugin files weren't deleted. Update got confused.
  • "The plugin does not have a valid header" — Plugin files are corrupted. The .zip extract failed.
  • "Parse error: unexpected token" — PHP version incompatibility. New plugin code uses syntax the old PHP doesn't support.

Check debug logs

  1. Enable WordPress debug logging (if not already on)
  2. Edit wp-config.php and add before "That's all, stop editing!": 
    define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
  3. Try updating the plugin again (it will probably fail again)
  4. Download wp-content/debug.log via FTP
  5. Search for the plugin name and "error"

The debug log shows the exact line where the update failed.

Check plugin folder state

Connect via FTP and look at the plugin's folder in wp-content/plugins/.

  • Folder exists but is mostly empty: Update partially extracted then failed
  • Two versions of the plugin folder (old-name and new-name): Update got confused about where to put files
  • Folder has lots of files but no main plugin file: Extract failed partway through

Take a screenshot or note which files are there. This helps you decide whether to roll back or manually fix.

Step 2: Immediate Fix - Deactivate the Broken Plugin

First priority: stop the broken plugin from running. A half-updated plugin can cause fatal errors that crash your whole site.

Option A: Via FTP (Best if admin is broken)

  1. Connect via FTP
  2. Navigate to wp-content/plugins/
  3. Find the broken plugin's folder
  4. Rename it to something like pluginname-disabled
  5. Visit your site. It should load again (no fatal error)

Renaming the folder deactivates the plugin instantly. WordPress can't find it, so it won't try to load it.

Option B: Via WordPress Admin (If admin works)

  1. Go to Plugins
  2. Find the broken plugin (it will show as inactive or have an error)
  3. Click "Delete" to remove it entirely
  4. Reinstall the old version from your backup or the plugin repository

If your admin is broken and you can't access it:

  1. Install and activate "Health Check & Troubleshooting" plugin via FTP (copy the plugin folder to wp-content/plugins/)
  2. Visit yoursite.com/wp-admin/admin.php?page=health-check
  3. You might be able to access a limited admin panel even with errors

Step 3: Roll Back to the Previous Version

The safest fix is usually to restore the version that was working.

Option A: From Backup (Fastest)

If you have daily backups via UpdraftPlus, BackWPup, or your hosting provider:

  1. Find the backup from before the failed update
  2. Restore just the plugin folder (not the whole site)
  3. Test the plugin to make sure it works

Most backup plugins let you restore individual folders. This takes 2 minutes.

Option B: Manual Rollback

If you don't have a backup, you can download the previous plugin version:

  1. Go to wordpress.org/plugins and search for the plugin
  2. Click the plugin name
  3. Look for "Advanced" or "Changelog" section
  4. Find the previous version number (e.g., if current is 2.5, download 2.4)
  5. Click "Download version 2.4"
  6. Extract the .zip on your computer
  7. Upload the extracted folder to wp-content/plugins/ via FTP (overwrite the broken folder)
  8. Go to Plugins and activate it

Why this works: The previous version was tested and working. You're just putting it back.

Data safety: If the failed update changed the database, rolling back the plugin code doesn't undo those changes. But usually failed updates don't change the database (they fail before that step). If you get errors after rolling back, see "Database Issues" below.

Step 4: Fix the Root Cause (So It Doesn't Happen Again)

Now that the site is stable, fix why the update failed.

File Permission Error

Error message: "Could not create directory" or permission denied

Fix:

chmod 755 wp-content
chmod 755 wp-content/plugins
chmod 755 wp-content/plugins/pluginname

WordPress needs write access to plugin folders. 755 means owner can read/write/execute, everyone else can read/execute.

Disk Space Error

Error message: Often no clear message, just "failed"

Check:

df -h

Look for your WordPress partition. If it's 95%+ full, that's your problem.

Fix:

  • Delete old backups from wp-content/backups/
  • Clear cache folders if you use a caching plugin
  • Delete unused themes and plugins
  • Ask your hosting to upgrade your storage

Memory Limit Error

Error message: "Allowed memory size exhausted" in debug.log

Check current limit: Create a file with <?php phpinfo(); ?>, upload it, and look for "memory_limit"

Fix: Edit wp-config.php and add: 

define( 'WP_MEMORY_LIMIT', '256M' );

Most plugins need 128-256M. If you're at 64M, updates will fail.

PHP Version Incompatibility

Error message: "Parse error" or "unexpected token" after update fails

Check your PHP version: Look at your hosting control panel or phpinfo output

Fix: Check the plugin's requirements. If it needs PHP 8.0 and you're on 7.4, you need to upgrade PHP or find a different plugin.

Workaround: Roll back to the previous plugin version and contact the developer. They might have broke compatibility with older PHP.

Download Failure

Error message: "Could not download" or "Timeout"

Causes:

  • Plugin server is slow
  • Your server's outbound bandwidth is throttled
  • Your hosting blocks outbound connections to certain IPs

Fix:

  1. Wait an hour and try again (plugin server might be down temporarily)
  2. Do a manual update instead (download the .zip yourself, upload via FTP)
  3. Contact your hosting and ask if they're blocking downloads from wordpress.org

Conflicting Plugin

To find which plugin is causing issues:

  1. Deactivate ALL plugins except the one you're trying to update
  2. Try the update. Does it work now?
  3. If yes, reactivate plugins one-by-one, testing after each
  4. When the update fails again, you've found the culprit
  5. Contact that plugin's developer or look for an alternative plugin

Step 5: Try the Update Again

After fixing the root cause, attempt the update again.

  1. Go to Plugins
  2. Find the plugin
  3. Click "Update Now"
  4. Wait (don't interrupt it)
  5. Check if it succeeded

If it fails again with the same error, you found the issue but didn't fully fix it. Go back to Step 4 and dig deeper.

If it fails with a different error: You fixed one problem but there's another. Go back to Step 1 and diagnose the new error.

Step 6: Database Issues (If Plugin Won't Activate After Update)

Rare scenario: Update completes, files extract fine, but when you try to activate the updated plugin, you get an error about the database.

This means the update tried to change the database but failed partway through.

Check what went wrong

  1. Enable debug logging (see Step 1)
  2. Try to activate the plugin
  3. Check debug.log for the exact SQL error

Common database errors:

  • "Duplicate column" — The update tried to add a column that already exists. Usually means the update partially ran before.
  • "Out of disk space" — Database file is too large and can't grow. Very rare.
  • "Syntax error in SQL" — The plugin has a bug in its database update script. Contact the developer.

Fix database issues

Option 1: Roll back and wait

Roll back to the previous plugin version. Wait a few days. The plugin developer might release a hotfix. Try updating again.

Option 2: Manually fix the database (Advanced)

If you know SQL and can access your database directly (via phpMyAdmin or command line), you might be able to manually run the migration. But this is risky—only do this if you're comfortable with databases.

Option 3: Fresh install

If the plugin's database changes are too complex to fix manually:

  1. Roll back to the previous version
  2. Export any data the plugin stores
  3. Deactivate and delete the plugin completely
  4. Download and install the new version fresh
  5. Re-import the data

This is tedious but guaranteed to work.

Real-World Failed Update Story

Scenario: WooCommerce update failed on a client's e-commerce site. The admin tried to activate the plugin after the failed update and got "Fatal error: Call to undefined function".

What happened:

  • WooCommerce update started downloading
  • Disk space ran out (old backups filled the drive)
  • Download stopped but the plugin folder was already partially replaced
  • The old version's main plugin file was deleted
  • The new version's main plugin file never downloaded
  • Plugin was left with no main file—fatal error on activation

Our fix:

  1. Renamed the broken plugin folder to disable it
  2. Deleted old backups to free up 12GB
  3. Restored the WooCommerce folder from a backup taken 2 days prior
  4. Activated WooCommerce—it worked
  5. Tried the update again—it succeeded

Total time: 15 minutes. Total data loss: zero.

Prevention: Stop Updates from Failing

1. Keep plenty of free disk space

WordPress needs 20% free space minimum. Monitor monthly. Most plugin updates need 50-200MB temporarily during extraction.

2. Keep PHP memory limit high

Set WP_MEMORY_LIMIT to 256M or higher. Large plugins need this.

3. Update during low-traffic times

Update at 2am, not during business hours. Less server load = fewer timeouts.

4. Test on staging first

If the plugin is critical, clone your site to a staging environment and update there first. Catch incompatibilities before production.

5. Keep a recent backup

Use UpdraftPlus or BackWPup to auto-backup daily. If an update truly breaks things, restore a backup.

6. Keep plugins updated regularly

Don't let plugins get 10 versions behind. Each update is a bigger jump and more likely to fail. Update every 2-4 weeks.

7. Check plugin compatibility before updating

Look at the plugin's changelog. Does it mention your WordPress version? Does it mention your PHP version? If the changelog says "requires PHP 8.0+" and you're on 7.4, wait or upgrade PHP first.

Plugin Update Failure Checklist

Update failed?

  • ✓ Note the exact error message
  • ✓ Enable debug logging and check debug.log
  • ✓ Disable the plugin immediately (rename folder via FTP)
  • ✓ Roll back to previous version from backup or download
  • ✓ Test the site—does it work now?

Now fix the root cause:

  • ✓ Check file permissions (chmod 755)
  • ✓ Check disk space (df -h)
  • ✓ Check memory limit (phpinfo)
  • ✓ Check PHP version compatibility
  • ✓ Deactivate all other plugins and try update again

Update succeeded?

  • ✓ Test the plugin's main features
  • ✓ Check for PHP errors in debug.log
  • ✓ Test the site frontend
  • ✓ Re-enable other plugins

The Real Talk

Plugin updates failing is one of the most stressful WordPress situations. Your site is broken, the plugin is half-installed, and you don't know if you'll lose data if you try to fix it.

Here's what you need to know: Your data is safe. The plugin files are the only thing broken. WordPress keeps backups of old plugin files before overwriting them. You can always roll back.

The fix is usually just deactivating the broken plugin and restoring a working version. Five minutes. That's it.

The scariest scenario is that you'll have to disable the plugin and wait for the developer to fix it. But even that isn't data loss—it's just missing functionality until it's fixed.

Know these steps. When an update fails, you'll stay calm. Deactivate, roll back, fix the cause, try again. Nine times out of ten, it works.