What to do when a WordPress update breaks your site

What to do if a WordPress update breaks your site

In my last post, I talked about the safest way to update WordPress plugins. Even if you take all those steps, an update still might have a hiccup. Don’t panic! Here are a few ways things can glitch, and how you can fix it.

It’s helpful to understand the basic process WordPress goes through when updating a plugin. First, it puts the site into maintenance mode (more on that below), then it deletes all the existing files for that plugin. It then downloads an archive of the new plugin, and unpacks it into the same folder. Finally, it marks the update as completed and you’ll see that glorious, green checkmark next to the plugin.

Update success!

But if that doesn’t happen, here are a few things that might be going on:

The plugin update just runs and runs and runs…

The most common issue I encounter when updating is that the process just keeps going and never actually says it’s done. This is most common on underpowered, shared servers (looking at you, Bluehost and HostGator!).

If it’s been more than a couple of minutes, try opening the plugins page in a new tab (leaving the current update running). Compare the version number on the new tab with the previous version number. You may find that the update actually did complete, it just never gave you that green checkmark. If that’s the case, just close the first tab and you’re good to go.

If it’s the old version and still says an update is needed, wait another minute or two and refresh the page. If it’s still the old version, try running the update again. And if you run into something else, read on.

Your site gets stuck in “maintenance mode.”

When WordPress runs an update, it first goes into maintenance mode, and will display a simple page to your visitors that says:

Briefly unavailable for scheduled maintenance. Check back in a minute.

It does this by adding a file called .maintenance in your home folder (including the leading period).

After the update completes, the .maintenance file should be removed automatically. But if the update stalls out and that file doesn’t get removed, your site will get stuck there.

To fix it, log in to your server via FTP, locate the home folder (usually /public_html/) and simply delete the .maintenance file. (If you don’t see it, you may need to tell your FTP program to show hidden files.)

Screenshot from FileZilla FTP
Using FileZilla to see a list of all the files in /public_html/. Click on the .maintenance file and hit delete!

The plugin didn’t install all the new files.

If the plugin update doesn’t complete, you might also end up with an empty folder for the plugin, or a folder with just some of the files installed.

For example, if you’re updating the Yoast SEO plugin, its files reside in the /wp-content/plugins/wordpress-seo/ folder. Since the update process requires removing the files, download a new zipfile, and then unzipping it back into the folder, if it stalls out and the new files don’t all get added back to that folder, you’ll run into problems.

There’s one file in every plugin that contains information about the plugin, such as the plugin name and the author. If that file doesn’t exist, the next time you load a page in your dashboard, WordPress will realize this and deactivate the plugin (and it will show a notice at the top of your screen).

However, if that file is there, but other files are missing from the plugin, you may see other errors, such as PHP Fatal Errors. You might also get the “white screen of death.”

Before WordPress 5.5, if you tried to reinstall a plugin, WordPress would kick out an error because the folder already exists. Now, if you upload a zipfile of the plugin, it should let you replace the existing folder.

If you don’t have a zipfile of the plugin, you can log in with FTP and delete the plugin folder completely, and then reinstall the plugin. Or, you can restore the plugin’s contents from the backup you made before updating.

You get the “white screen of death.”

This is similar to the above – but it happens when there is a “fatal error” of some kind…and you end up with just a blank, white screen and nothing else (or maybe just a scary error message).

It usually happens because of an incompatibility between your server and the new version of the plugin. In this case, the best thing to do is log in with FTP, delete the plugin’s folder, and then restore the previous version of the plugin from a backup.

It’s also possible to download a previous plugin version directly from the WordPress repository. If you’re viewing a plugin’s page, go to the “Developers” tab and you can download the zipfiles of previous versions from there.

If you run into the white screen of death, I encourage you to visit the plugin’s page at wordpress.org, go to the “Support” tab and look in the forums to see if anyone else has run into a similar issue. If not, consider creating a new thread there and letting people know what happened. Be as specific as possible, as that will help the developer get things sorted out quickly.

It updated fine, but now it doesn’t work quite right.

If it’s a minor issue, try updating all your other plugins, your theme, and WordPress core to the latest version. Sometimes that will fix it, as it brings everything current.

If it’s a major issue, you may want to consider rolling back to the previous version of the plugin, either from a backup, or, if it’s a plugin from the WordPress repository, using the WP Rollback plugin. Then post in the support forms as I described above. Most plugin authors are incredibly helpful and responsive, and if you’re nice — and give them as much information about the issue as possible — they’ll usually bend over backwards to help you get it sorted out.

If you don’t want to deal with any of this stuff…

…let us take care of updates for you! our Inner Peace and Zen Master WordPress support plans include regular updates, done by real humans (not an automated process) — and if updates glitch or break anything, we’ll fix it. We usually have things fixed up before anyone (including you) even knows something went wrong.

Filed Under:

Tagged With:

Related Posts


  1. Thanks, this article was very useful to teach me about the .maintanence file. I was able to quickly resolve my issue with your help. Kudos!

  2. Thanks, this article was very useful to teach me about the .maintanence file. I was able to quickly resolve my issue with your help.

  3. This helped me so much, thank you so very much! My sidebar was down below the content only on the homepage, and I couldn’t figure it out. But after I read that it could be a problem with an individual post and nothing to do with stylesheet or anything like this, I checked my recent pages/posts and I found a weird code with div (probable it was there due to me pasting the content). When I deleted the two first and two last lines of the page html, the problem disappeared. Thank you!!

  4. I am hosting my site and have my domain with Go Daddy . I clicked ” update all” on the WP manager page; (My account >WordPress>Settings).
    What I did is update all the plugins and a theme. After doing that my site went down with error 500 and I could not restore my site with my backups ( I only had 1 backup and it was the back up of same day I performed this change).

    What happened here na and how can I prevent this from happening again.

    Thanks you in advance

  5. Your article pointed me in the right direction for 2 things. I had an awful white screen of death and no backups. Then I made it worse by “establishing a database error” resetting the password to get into the backend files. Your article first showed me exactly how to fix the database error, done in 2 minutes! Then your article suggested that I reach out to the theme developers. I showed them the error, and showed them the code in the file with the error and within 10 hours I had a response. Their support team gave me a snippet of code to replace in the functions file and boom, I’m back up and running. (and I set up backups!!) Thanks. I don’t normally comment on articles, but you saved me a lot of time. PS. this is for a local non-profit that really can’t afford to pay someone to fix this, I did this just because I used to be a part of the school. So this really helped a school with a very small budget NOT have to hire someone to fix the white screen of death. I felt you deserved a kudos. So Kudos.

  6. Hi there,
    I tried updating WooCommerce but before I did, I created a full-site backup on Google Drive using Updraft Plus. After trying to update WooCommerce, I got the white screen of death. Therefore, I cannot log back in to the dashboard to retrieve these files from Google Drive. What should I do?

    1. Hi Gary,

      Follow the instructions in the “You get the “white screen of death.”” Section above. In short:
      – Connect to your server via FTP
      – Navigate to the /wp-content/plugins/ folder
      – Rename the “woocommerce” folder to something else, like “woocommerce-broken”

      That will deactivate WooCommerce, and if the fatal error was coming from WooCommerce, your site should now load again. Then you can use UpdraftPlus to restore the site.

  7. Andrew thank you so much. I got a fatal error after updating Google Analytics plugin and this tutorial saved me. So thankful!!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.