Fixing "Briefly unavailable for scheduled maintenance" in WordPress

You started an update and suddenly the whole site shows nothing but: “Briefly unavailable for scheduled maintenance. Check back in a minute.” Minutes later, nothing has changed. What happened: an update was interrupted and WordPress never cleared the maintenance flag. The fix takes less than a minute. Cleaning up properly afterwards takes a bit longer.

If your install runs in German, you see the official translation instead: “Diese Website ist aufgrund planmäßiger Wartungsarbeiten vorübergehend nicht verfügbar. Bitte versuche es in wenigen Minuten erneut.” Same message, same problem, same fix. Everything below applies to both.

What the Message Says in English and German

The German wording comes from the official WordPress translation on translate.wordpress.org. If your theme or a plugin changed the text, you’ll see something different. That usually means a custom maintenance page is involved (more on that below).

What’s Behind It: the .maintenance File

During an update, WordPress creates a file called .maintenance in the root directory. It contains a single line of PHP that stores the current Unix timestamp in a variable called $upgrading. On every request, WordPress checks early in the load process whether the file exists. If it does, it stops and prints the maintenance message instead of your site. When the update finishes, WordPress deletes the file again.

If the process breaks off in between, the file stays. So it’s not a real defect, just a forgotten flag. The WordPress developer reference marks the function behind this, wp_maintenance(), as internal to core, so there is nothing for you to code.

Does It Clear Itself After Ten Minutes?

Almost. The source of wp_is_maintenance_mode() contains a ten-minute rule: if the timestamp in $upgrading is ten minutes old or older, WordPress treats maintenance mode as over. A stale file should therefore block the site for about ten minutes, not forever.

If the message stays longer for you, there are a few possible reasons. A page cache or CDN may keep serving the maintenance page. Or an update is still running and renewing the file. Delete the file in any case, so the next update attempt doesn’t start from a leftover.

Why Maintenance Mode Gets Stuck

An update has to download, unpack, copy files and finally lift the lock. It can break at any of those steps:

• Timeout: The server kills the PHP script before the update is done. On cheap shared hosting this happens with larger packages.
• Closed browser: You close the tab or lose the connection while the update is running.
• Bulk update: You update ten plugins and a theme at once. The more runs in parallel, the sooner the server hits a limit.
• Memory limit: A plugin needs more memory than PHP allows while unpacking or initializing, and the script dies with a fatal error.
• Full disk or wrong permissions: WordPress can’t write or move files.

Knowing the cause matters, because it decides whether the next attempt works. If you hit a memory limit, don’t just repeat the update blindly.

Finding and Deleting the .maintenance File

The file sits in the root directory of the install, right next to wp-config.php and the wp-content folder. Because the name starts with a dot, many tools hide it.

Via FTP or SFTP

1. Connect with the credentials from your host.
2. Turn on the display of hidden files in your client. Depending on the program, the option is in the server, view or settings menu.
3. Go to the WordPress root, often public_html, htdocs or a folder for the domain.
4. Delete .maintenance.

Via Your Host’s File Manager

Most hosts offer a file manager in the customer area. There too you usually have to enable hidden files first. Where the option lives differs by provider, typically in the file manager’s settings.

Via SSH

With SSH access, this is the fastest route. Go to the root directory and list all files, hidden ones included:

ls -la

If .maintenance shows up, remove it:

rm .maintenance

Then reload the site. It should be reachable at once. If it isn’t, clear the cache of your caching plugin and, if you use one, the CDN.

Afterwards: Spotting a Half-Finished Update

The site being back doesn’t mean the update was complete. First find out what was affected. Under Dashboard → Updates in the backend you see which updates are still pending. Those are your candidates.

Plugins and Themes

Typical signs of an incomplete plugin or theme update:

• The backend reports a critical error or the site stays white.
• A plugin is listed as active but some of its features are missing.
• The plugin folder in wp-content/plugins/ is missing or suspiciously empty.

Since WordPress 6.3 there is a rollback for failed manual plugin and theme updates. WordPress first moves the old version to wp-content/upgrade-temp-backup/ and restores it if the update fails. On success the backup is deleted. According to the announcement on make.wordpress.org, this applies explicitly to manual plugin and theme updates, not to core updates. The announcement doesn’t say whether bulk updates are covered, so don’t rely on it.

If you find a half-finished plugin folder, deactivate the plugin in the backend if you can still get in. If you can’t, rename the folder via FTP, for example to plugin-name-broken. Then install a fresh copy of the current version.

Reinstalling the Core Update

You can also reinstall WordPress itself. In the backend that’s the re-install button under Dashboard → Updates. With WP-CLI over SSH:

wp core version
wp core update --force --version=YOUR_VERSION

Replace YOUR_VERSION with the number wp core version prints. According to the WP-CLI docs, --force forces the update even when the installed version is higher than the requested one.

To check whether the core files are intact, run:

wp core verify-checksums

The command compares your files against the official checksums and reports mismatches or missing files. A mismatch can come from an aborted update, but also from deliberate changes. Read the reported file names before you overwrite anything.

After that, finish the original update in the backend properly, ideally one plugin at a time, and check the home page, login, forms and the shop checkout if you have one.

If the Site Still Hangs Afterwards

If the .maintenance file is gone and the site still won’t load, maintenance mode wasn’t the actual problem. The interrupted update left a deeper issue behind. The site then usually shows a different error: a critical error, a white screen or a 500 error. Sort those out via the overview of WordPress errors. Here a current backup helps you return cleanly to the state before the update.

If you’re short on time and stuck, our WordPress emergency service can help.

Using a Custom Maintenance Page on Purpose

You can replace the grey default message. WordPress looks for a file called maintenance.php in the wp-content folder and serves it instead of the default text while maintenance mode is active. That works for updates and for maintenance windows you plan yourself.

One thing to know: according to the source, WordPress includes your file and then ends execution. It does not set the HTTP status for you in this case. You do that inside the file:

<?php
http_response_code( 503 );
header( 'Retry-After: 600' );
header( 'Content-Type: text/html; charset=utf-8' );
?>
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Maintenance</title>
</head>
<body>
  <h1>We'll be right back</h1>
  <p>We're updating the site. Please try again in a few minutes.</p>
</body>
</html>

Without the 503, search engines would see your maintenance page as a normal page with status 200 and might index it. The generator at the bottom builds a page like this for you.

HTTP 503 and Retry-After: What Matters for SEO

According to the source, the default message goes out with status 503 and the header Retry-After: 600, plus no-cache headers so the browser doesn’t hold on to it. 503 means “service unavailable” and tells search engines the outage is temporary and they should come back later. The 600 is seconds, so ten minutes.

A short outage with a 503 is therefore harmless for search. It gets critical when maintenance mode hangs for days, or when a custom page wrongly answers with 200. After deleting the file, check in the browser or with curl -I https://your-domain.com/ that the home page answers 200 again.

Stopping It from Happening Again

• Update one at a time. One plugin after another, with a quick look at the site each time. If something breaks, you know which update did it.
• Keep the tab open until WordPress reports completion.
• Back up before updating. A backup you’ve restored at least once. A backup nobody has ever tested is a hope.
• Use staging. Test bigger updates on a copy first → Update WordPress safely with staging.
• Know your resources. The PHP memory limit and maximum execution time of your hosting plan decide how large an update can run through.

The file is gone but the site still hangs? Then there’s more to it. Drop us a line and we’ll bring the site and the update to a clean finish. If updates regularly turn into a gamble for you, our WordPress maintenance takes them off your plate, with a backup and staging test before every update.

And so visitors don’t see the grey default message during the next update: a custom maintenance page with a correct 503 status, generated in five minutes.

Also available as a standalone page with all guides: maintenance page generator.