Updates to your WordPress site become available all the time, whether these are updates to Core, Themes, or Plugins. Since many updates build off each other, the longer you wait to update, the greater the risk of something going wrong. Smaller incremental updates makes it easier to identify and fix an issue if there is one.

While many of WordPress’ core updates happen automatically, Major release updates, along with updates to your Theme and Plugins, do not. People are often nervous to push that update button, because there’s a chance it could result in a broken site. However, outdated themes, plugins and core WordPress files are a surefire way to a hacked site – so updates are necessary. But what should you do if an update breaks your site?

Your first response is probably going to be sheer terror, followed by panic, especially if you’ve just broken your LIVE WEBSITE. (By the way, we recommend making updates on a staging site, so check back next week to learn how to do that.) This post covers various ways an update can potentially break your site, and provides instructions on how to “un-break” it as quickly as possible.

The Update Process

When WordPress core gets updated, WordPress goes into what we call “Maintenance Mode.” Instead of seeing your website, a visitor will see a message stating that the site is down briefly for maintenance, and to check back in a moment. (By the way, this screen is customizable.) This is to make sure nothing looks broken on your site while the update is happening. During this time, WordPress deletes all existing files for that item, and replaces them with the new version. Once the update is run successfully, WordPress goes out of Maintenance Mode and you get a notification confirming success.

Plugin update successfully confirmation

The success message of a Plugin update

Stuck in Maintenance Mode?

It is possible for something to go wrong with the update, causing your site to get stuck in Maintenance Mode. If it stalls, the most common issue has to do with a file (called .maintenance) that WordPress uses to put your site into Maintenance Mode. If it fails to be deleted afterward, your site will be stuck with that message.

Fortunately, getting your site out of Maintenance Mode is a pretty easy fix – you just need to manually delete that .maintenance file. But in order to GET TO that file, you need to have access to your sites files via either your hosting account or FTP. So it is important to always have those URL’s and logins onhand, in case you need them in a pinch. It’s also useful to familiarize yourself with an FTP program – like the free FileZilla – so you can quickly take care of little issues like this when they arise and aren’t scrambling to find passwords. Once you have logged in via FTP, go to the site’s root (usually in a folder called public_html) and delete the file!

WordPress maintenance file

There’s the culprit!

If you can’t do it yourself, your host should be able to delete it for you, although sometimes for a fee. It’s a good idea to get familiar with your host’s maintenance and support policies, as some may charge pricey fees to fix your site. You may find that having a developer who can be on-call in times of emergency is a better option.

After getting your site out of Maintenance Mode, it’s always good practice to check your site. The update may have disabled your theme or plugin if it broke during update.

My Site is Broken, and It’s Not Maintenance Mode’s Fault. Who Is Responsible??

Sometimes updating core, or your themes or plugins, can cause other things to break on your site. When this happens, you will need to find the issue and fix it. In the meantime, you can roll back to a previous version of the plugin or theme (or even WordPress core version) while you work out a fix.

The easiest way to do this, is to simply use a backup of your site and revert to the most recent version. (You do have a Backup system in place for your site, right? If not, don’t worry, we’ll be covering that topic on Mar 21, so stay tuned!). This is not a permanent fix – you will still have to run the updates at some point, and likely soon if there are security patches involved. Fixes might involve changing some code in your theme, settings in your plugin, or replacing a plugin entirely.

Aside from backups, you can manually replace the files via FTP or use the WP Rollback plugin, which gives you the ability to roll back to previous versions of a plugin or theme from the dashboard. Can it rollback itself? I do not know the answer to that and thinking about it makes my head hurt.

When the Culprit is a Core Update

To be frank, a Core update is almost never the reason for your site breaking. WordPress puts a lot of effort in maintaining backwards compatibility – meaning, it still supports deprecated functions as best it can, for those who are running old versions. There is a lot of debate about this, because it can hinder progress in the WordPress project, and arguably, nobody should be running old versions of WordPress to begin with. But that is a discussion for a different time.

WordPress Core updates are carefully vetted. If your site breaks after a core update, it is most likely a plugin or theme that has not updated to support the most recent WordPress version. All WordPress developers who have contributed either themes or plugins to the online repository get a direct email for every core update, outlining the things that are going to change. This gives the developers time to update their plugin or theme to support this version. But not all theme and plugin developers are vigilant about this. Fortunately, WordPress tells you when a theme or plugin in the repo has not been updated in a long time, or when it has not yet been tested with your version of WordPress.

Plugin WordPress Version screen

You can see when the plugin was last updated, and which version it has been tested with, in the Plugin Repo on wordpress.com

But it’s not impossible for a Core update to go wrong! When it does, the WordPress team will push out another update that fixes things as soon as possible. However, it may require you to manually update WordPress. The Codex has information on how you can run a manual WordPress update.

When the Culprit is a Plugin

Sometimes, you run a bunch of updates at one time and aren’t sure which one was the culprit that broke your site. You can start by deactivating all your plugins, and reactivating them one by one to check which one is causing the broken site.

Once you find the plugin responsible for the break, you have a few options:

  • Check online to see if anyone else has had the problem. If so, there may be a known fix you can implement.
  • Contact the plugin developer about the issue. They will probably like to know when there is a conflict. Tell them which version of WordPress you are running, which theme, and all the plugins and versions you have running. This can help to narrow down the issue. They may have further instructions for you like checking your server error logs to give them more information.
  • Disable the plugin. If it’s not a critical plugin, you can disable and delete it, or replace it with another plugin with similar functionality.
  • Revert to a previous version of the plugin. While you are looking for a fix, you can revert to a previous stable version of the plugin.
  • Hire a developer. A knowledgeable developer may be able to fix it. It’s important to note, however, that you should [almost]never edit another plugin’s core files. When plugins are updated, all the files will be overwritten by the new version, including your changes. But I say [almost] never, because sometimes the developer will work out a quick fix for you to apply to the plugin yourself while they work on releasing a new version.

Disabling a Plugin

If you aren’t sure which plugin it was, disable all your plugins and reactivate until you find the culprit. If you don’t have access to the Admin, you can disable the entire Plugin directory to regain access. Rename the Plugins directory to _Plugins. Navigate back to your Admin panel, and go to the plugins directory. Go back to FTP and change the Plugins directory back to Plugins. This disables all your plugins, and you can now go in and reactivate them one by one until you find the broken one.

FileZilla screenshot

Delete the offending plugin to restore access to your site

When the Culprit is Your Theme

Sometimes, themes are responsible for a site break. Did you use a child theme to make code changes to your theme? If you made changes directly to your commercial or free theme, running an update will overwrite all of these changes. Never make code updates directly to your theme, unless it is a custom theme and you know what you are doing. Check out the Codex for more information on Child Themes!

It may also be that your theme wasn’t prepared for the WordPress update. This process is similar to the plugin troubleshooting process.

Disabling a Theme

If the theme is the issue, go into your Themes Admin and activate the default WordPress theme. These are typically named by year.For example, in 2017, the default theme was called twenty-seventeen. If you do not have access to your Admin, here is where our trusty FTP client comes in handy. Navigate to your Themes directory [mywebsite.com > wp_content > themes], and rename the offending theme. This will deactivate it, and activate the default theme automatically.

Activating the default theme will let you know if it’s a theme issue or not. If the problem still persists after activating the default theme, then it is likely a plugin issue. If it is a theme issue, then check for updates with the theme creator, or choose another theme that supports the current WordPress version. It is also useful to contact Support and notify them of the issue. If the theme was from the WordPress Repo, leave a post in the forums. If it was a commercial theme, contact their support directly to report it.

When Your Host is to Blame

If you see a 500 Internal Server Error on your site, this means you’ve got a hosting issue. Your hosting may be down, or you have run out of memory on your server. Contact your hosting support to solve this problem.

The White Screen of Death

The White Screen of Death is how we WordPressers fondly refer to a site breaking so badly that all you see is a white screen. No website, no code, nothing: just white. This is the worst, and this is the point people start to panic. But don’t panic – we can troubleshoot this by deactivating our plugins and themes, which will reset everything and restore your access to the Admin for troubleshooting. Use the information above to first disable your Plugins directory, and see if your site comes back online. Next, change to a default WordPress theme. If the site is STILL white screening, you may have a corrupt version of WordPress. The best thing to do is a manual WordPress update and replace all your core files with a fresh install.

Information to Always Have on Hand In Case of an Emergency

It’s easy to lose track of key information if your site has never broken before. But the first time it does, you’ll want to have as much information on hand as possible so you, your developer, or your host can troubleshoot. Below is a list of items you will need:

  • Your domain registrar
  • Your hosting login
  • Access to your database and files via cPanel or FTP
  • A FTP client like Filezilla
  • Your host’s Website Support policy
  • The number of a good developer who will work with you in emergencies!

Next week: Don’t Break Live! Making Sure WordPress Updates Don’t Break Your Site

Of course, in an ideal situation, you will do all your updates on a Staging Website, so you can catch and fix any potential issues before you update your live site. Fear not, for next week, we will be talking Staging Sites! Stay tuned to learn how to set up your own Staging Site and ensure you never break your live website from an update again.