Briefly Unavailable for Scheduled Maintenance, and How to Clear It
The message comes from one small file which WordPress writes when an update starts and deletes when it ends. Why it sometimes stays, and the four steps which I take to clear it.
Mike Lopez
Designs and builds websites and B2B software
On this page
“Briefly unavailable for scheduled maintenance. Check back in a minute.” is the page which WordPress shows while it updates a plugin, a theme or itself, and it comes from a small file named .maintenance which WordPress writes into the main folder of your site when the update starts and deletes again when the update finishes. When an update stops halfway, the file stays behind and every visitor sees the message, and I think it’s really useful to know that WordPress ignores the file once it is ten minutes old, so the fix is either to wait ten minutes or to delete that one file. This website showed the message to everyone in August, the dashboard included, after a theme upload through my host’s deployment tool left the file in place, and nothing else was wrong with the site.
This post goes through where the message comes from, why it sometimes stays, and the steps which I follow to clear it, in the order which I would try them.
Where the message comes from
The wording lives in WordPress core, in a function called wp_maintenance(), which runs on every page request and looks for the .maintenance file in the same folder as wp-config.php. The file itself holds a single line of PHP with the time at which the update started, written by the updater’s maintenance_mode() method for plugin and theme updates and by the core updater for WordPress itself, so the site knows that something is being replaced and stops serving pages until it is done.
While the file is there, WordPress answers every request with the message and an HTTP status of 503, which means the server is unavailable for now, together with a Retry-After: 600 header that tells browsers and search engines to come back in ten minutes, as the core source shows. It mostly passes in a second or two, because a normal update writes the file, swaps the files and deletes it before anyone notices.
Which updates turn it on
Updating an active plugin turns maintenance mode on, and so does a single click on Update now on the Plugins screen, because that click runs the same bulk updater which a batch of plugins uses, and a batch turns it on once for the whole group and off again at the end. The active theme works the same way, a WordPress core update always does it, and the automatic updates which run in the background do it for everything except translations. On a single site an inactive plugin updates without it, since nothing on the site is running that code.
Why the message sometimes stays
The file only goes away when the update reaches its last step, so anything which stops an update in the middle leaves it behind. The usual causes are a browser tab closed during a batch of updates, a server which times out on a large plugin, a connection which drops, or a tool outside WordPress which starts an update and does not finish it. In my case the file was left by a deployment through my host’s API, and only the first upload which added new files to the theme did it, while later uploads which changed existing files went through cleanly.
The message then stays for up to ten minutes and goes away on its own, because WordPress’s wp_is_maintenance_mode() compares the time in the file with the current time and treats anything ten minutes old or more as finished. That is what happened on this website, which came back by itself after about ten minutes, and I suppose it’s the reason why so many people find the message has cleared by the time they look for a fix.
How to clear it
These are the steps which I take, and the first one is mostly enough.
1. Wait ten minutes and reload
Reload the page in a private window after ten minutes, so the browser does not show you a saved copy. If the site is back, the stale file is now ignored, but it is still sitting in the folder, so I would delete it anyway in step 2 the next time that you are in your hosting panel.
2. Delete the .maintenance file
WordPress’s own troubleshooting FAQ and its guide to common errors give the same fix, to delete the .maintenance file from the root folder of your site, which is the folder holding wp-config.php, wp-content and wp-admin. You can reach it through your host’s file manager or through an FTP or SFTP app, and since the name starts with a dot, the file may only show when hidden files are switched on in the app which you use.
On Hostinger, the route in its own tutorial for this message is Files, then File Manager, then the public_html folder of the site, where you right-click .maintenance and choose Delete. WP Engine’s support article gives SFTP or its SSH Gateway, where the command is rm .maintenance.
3. Clear the cache if the message is still there
If the file is gone and visitors still see the message, a caching plugin or the host’s cache is mostly serving a copy of the page which it saved during the update, which is why WP Engine adds a cache purge as the next step. I would purge the cache from the plugin’s settings or the hosting panel, then check the site in a private window again.
4. Finish the update which was running
The update which wrote the file did not finish, so the plugin or theme behind it may be half replaced. I would log in, open Dashboard, then Updates, and run that update again on its own, then open the home page and the page that matters most to you, such as the contact form, as I describe in my post on how to update WordPress plugins safely. If the dashboard shows a critical error instead, the recovery mode email which WordPress sends to the administration address opens the site with the faulty plugin paused.
| What you see | What it usually means | What I do |
|---|---|---|
| The message for a few seconds during an update | The update is working | Nothing, wait for it to finish |
| The message for several minutes | An update stopped and left the file | Wait until ten minutes have passed, or delete .maintenance |
| The message on the dashboard too | The same file, which blocks every page including wp-admin | Delete the file through the hosting panel or SFTP |
| The message after the file is deleted | A cached copy of the page | Purge the cache and check in a private window |
| A critical error after the site is back | The interrupted update left a plugin broken | Run the update again, or use the recovery mode email |
A maintenance page of your own
WordPress lets you replace the default message with your own page through a file named maintenance.php in the wp-content folder, which core treats as a drop-in, but in WordPress 7.1 that drop-in sends no 503 status unless it sets one itself, and the change which adds it is in the code for version 7.2, which has not been released yet. For a small business site I think the default message is fine, since it shows for seconds on a normal day.
Where to start
If your site shows the message right now, note the time, wait ten minutes and reload in a private window, and then open your hosting panel’s file manager, find .maintenance beside wp-config.php and delete it, before you run the update which stopped once more on its own. It’s also worth checking how your updates run, since a batch of thirty plugins clicked through at once is the most common way to leave the file behind, and if you share your posts on LinkedIn, the LinkedIn preview image is worth a look after any round which updated your SEO plugin.
Frequently asked questions
How long does WordPress stay in maintenance mode?
A normal update keeps the site in maintenance mode for a few seconds, and a stuck one for ten minutes at most, because WordPress ignores a .maintenance file once the time written in it is ten minutes old.
Can visitors see my site while the message shows?
No, every page shows the message to everyone, logged in or not, and the dashboard shows it too, which is why the fix runs through the hosting panel or SFTP rather than through wp-admin.
Is it safe to delete the .maintenance file?
Yes, the file only holds the time at which an update started, and WordPress deletes it itself at the end of every update, so removing it only tells WordPress that the update is over, and the update which stopped should then be run again.
Why can’t I find the .maintenance file?
File managers and FTP apps mostly hide names which start with a dot, so switch on hidden files in the app’s settings, and look in the folder which holds wp-config.php, which is public_html on many hosts. If the file is not there, the message is a cached copy and the cache needs a purge.
