Fixing the Briefly Unavailable for Scheduled Maintenance Error in WordPress

There’s an error in WordPress which occurs rarely when an update fails to complete. It usually happens when you update the WordPress core itself, compounding the fear factor. The message your receive is “Briefly unavailable for scheduled maintenance. Check back in a minute”. In this article I’ll take a look at why this happens and how you can resolve the issue.

I thought I’d give you a bit more information than other articles usually delve into so I’ve split the article into two sections, the quick fix/quick explanation and the longer version – in case you’re interested in details.

The Quick Fix

As a safety precaution and an indicator to users WordPress puts the site in maintenance mode before starting the update. This prevents users from trying to save data during the process for example. Once WordPress completes the update process it takes the website out of maintenance mode, thus restoring normality.

If something happens before the site is taken out of maintenance mode (this usually means a PHP timeout) the execution of code stops so the site remains in maintenance mode indefinitely. All we need to do is figure out how WordPress achieves maintenance mode and undo it manually.

Luckily it’s all very simple. WordPress places a hidden file into your main directory named “.maintencance”. In case you’re not familiar with these types of files: this is a dotfile. Dotfiles are hidden files on Unix based systems like Linux or OSX. Deleting it may be difficult without the right tools since you may not see them in a normal directory listing.

Method 1: Using FTP

If you are using an FTP program to view your remote files you can usually enable the “view hidden files” option. This is most often found in the “view” menu of the program. If you can’t find this option, consult the documentation of your application. Once switched on you should see the “.maintenance” file in the list. Simply delete it to make your woes go away.

Method 2: Using The Terminal

If you are using an SSH connection to view your server’s files you can view hidden files by typing the “ls -a” command. With the terminal you don’t need to list a directory to delete files so you can just navigate to your WordPress root folder and type “rm .maintenance” and that’s it.

Still Having Issues?

In the majority of cases simply removing this file will get everything to pop back into place. According to the WordPress Codex FAQ:

To stop that message from being displayed to vistors, just delete the .maintenance file. The automatic upgrade should be executed again, just in case it failed.

This essentially means that once you remove the file the update is performed again. If something seems wrong, or perhaps the update failed once more, your best bet is updating WordPress manually. The Manual Update section in the Codex does a pretty good job of explaining this.

You’ll need to grab the latest WordPress files and extract them on your computer. Follow that up by deactivating all your plugins. Then, through FTP or SSH access, delete the wp-admin and wp-includes directories in your WordPress root folder. Upload the wp-admin and wp-includes directories from the newly extracted files.

Once done, upload all files that go in the root directory (wp-login.php, wp-cron.php, etc.). You can safely overwrite every file and folder except two. Do not overwrite wp-config.php or the wp-content folders. wp-config.php holds your configuration, if you overwrite that file you’ll loose access to your database. The wp-content houses your themes and plugins, deleting or overwriting that folder may cause you to loose your themes, or changes you’ve made to them.

Once you’re done WordPress may ask you to update your database but otherwise the dreaded “Briefly unavailable for scheduled maintenance. Check back in a minute” message should now disappear and everything should be back to normal.

Digging Deeper

I always like to try and explain the why of the situation, so let’s dig a bit deeper to see exactly what’s going on under the hood. The maintenance message is displayed when a specific set of conditions are met. This can be seen in the inline documentation of the “wp-includes/load.php” file. The following can be found starting at line 145, just before the wp_maintenance() function.

Checks for a file in the WordPress root directory named “.maintenance”.
This file will contain the variable $upgrading, set to the time the file
was created. If the file was created less than 10 minutes ago, WordPress
enters maintenance mode and displays a message.

The default message can be replaced by using a drop-in (maintenance.php in
the wp-content directory).

Looking closely at this function you can see that you can actually add your own custom maintenance message by plopping a file into the wp-content directory named “maintenance.php”. If this file exists it will be displayed, otherwise the default message will be used.

The update procedure itself is well documented in “wp-admin/includes/update-core.php” starting with line 730 before the update_core() function. A small excerpt from the documentation shows the steps taken, step 2 is the creation of the maintenance file, step 6 is the removal.

1. Test unzipped location for select files to ensure that unzipped worked.
2 . Create the .maintenance file in current WordPress base.
3. Copy new WordPress directory over old WordPress files.
4. Upgrade WordPress to new version.
4.1. Copy all files/folders other than wp-content
4.2. Copy any language files to WP_LANG_DIR (which may differ from WP_CONTENT_DIR
4.3. Copy any new bundled themes/plugins to their respective locations
5. Delete new WordPress directory path.
6. Delete .maintenance file.
7. Remove old files.
8. Delete ‘update_core’ option.

The function that actually creates the maintenance file is called maintenance_mode() and can be found in “wp-admin/includes/class-wp-upgrader.php”. You can see how it adds the $upgrading variable set to the current time. If the function is called with true as the first parameter it simply deletes the file. if the upgrade procedure fails any time before this delete method is called the site will be stuck in maintenance mode.

Conclusion

“Briefly unavailable for scheduled maintenance. Check back in a minute” can seem like a scary message if it your site is stuck on it, but it’s one of the more benevolent ones out there, fixing it is pretty easy and it usually doesn’t mean any database issues afterward.

We hope this article helped you learn how to fix the briefly unavailable for scheduled maintenance error in WordPress. You may also want to see our post on how to fix error establishing a database connection error, which is one of the most common errors in WordPress.

If you’ve ever bumped up against a particularly stubborn message which took extra effort to get rid of, let us know!