Fix a Failed WordPress Update: Delete .maintenance

5/5 - (1 vote)

Some links on this page are affiliate links. If you buy through one, WPNeon earns a commission at no extra cost to you. It does not change what we recommend — see how we review.

Delete the file called .maintenance from your site’s root folder, the one that also holds wp-admin, wp-includes and wp-config.php. That one file is what holds the site in maintenance mode and what produces the “An automated WordPress update has failed to complete” warning in your dashboard. Remove it, reload the site, then run the update again. WordPress writes .maintenance into the site root at the start of every core, plugin and theme update, and deletes it again when the update finishes. If the update is interrupted before that, the file is left behind and the site stays in maintenance mode long after nothing is happening. Visitors get “Briefly unavailable for scheduled maintenance. Check back in a minute.” and you get the failed-update nag in wp-admin. Both come from the same file. Also read: 10 Common WordPress Errors and How to Fix Them

Delete the .maintenance file

The file sits in your WordPress root folder, next to wp-admin, wp-includes and wp-config.php. On most hosts that folder is called public_html, htdocs or www. Its name begins with a dot, which means most tools hide it until you tell them not to. That is the single most common reason people conclude the file “isn’t there”. Use whichever of the three routes below you already have access to. They all do the same thing.

Route 1: your host’s file manager

  1. Log in to your hosting control panel and open its file manager.
  2. Turn on hidden files. In cPanel’s File Manager this is under Settings, as an option to show hidden files or dotfiles. Other panels word it as “show hidden files”.
  3. Open the folder that contains wp-admin and wp-config.php.
  4. Select .maintenance and delete it.

Route 2: FTP or SFTP

  1. Connect with an FTP client such as FileZilla, using the credentials from your host. Use SFTP if your host offers it, because plain FTP sends your password unencrypted.
  2. Tell the client to show hidden files. In FileZilla that is Server, then Force showing hidden files.
  3. Open your WordPress root folder.
  4. Right-click .maintenance and delete it.

Route 3: SSH

If you have shell access this is a two-line job. Change into your WordPress root, then remove the file: 
cd /path/to/your/site
rm .maintenance
Run ls -a first if you want to confirm the file is there before removing it. Plain ls will not show it.

Then finish the job properly

Deleting the file clears the symptom. These four steps clear the cause.
  1. Reload your front page. It should come back immediately.
  2. Clear your page cache and CDN cache. If you skip this, visitors keep being served the maintenance notice from cache and you will think the fix failed.
  3. Run the update again. Go to Dashboard > Updates. The first attempt did not finish, so whatever you were updating to probably is not installed yet.
  4. Check the version. The WordPress version shown at the bottom right of the dashboard should now be the one you expected.

If there is no .maintenance file

Work through these in order before you reinstall anything.
  • Confirm hidden files are actually showing. Toggle the setting off and on and look again. This catches most cases.
  • Confirm you are in the right folder. If you cannot see wp-config.php and wp-includes in the same listing, you are not in the WordPress root. On multisite and subdirectory installs the root is not always the domain’s top folder.
  • Clear the caches and log out and back in. The dashboard nag can survive in a page cache or object cache after the file has gone.
  • Assume the update half-finished. If the file is genuinely gone and the site still misbehaves, core files may have been part-replaced. Reinstall core by hand, below.
Before you touch core files, take a backup you can actually restore from. UpdraftPlus and Jetpack both do this, and so does almost every host’s own backup tool. Our roundup of WordPress backup plugins compares them if you have not set one up yet.

Reinstall WordPress core by hand

This is the official procedure from the WordPress documentation, and the order matters. Note especially step 6: uploading the new wp-content folder over the top of yours will destroy your themes, plugins and uploads.
  1. Download the latest WordPress release from wordpress.org and unpack the zip on your computer.
  2. Deactivate your plugins.
  3. Delete the old wp-includes and wp-admin directories on the server.
  4. Upload the new wp-includes and wp-admin directories in their place.
  5. Delete .maintenance from the root if it is still there.
  6. Upload the individual files from the new wp-content folder into your existing wp-content folder, overwriting as you go. Do not delete your existing wp-content folder, and do not delete anything inside it.
  7. Upload all the loose files from the root of the new version into your existing WordPress root.
  8. Visit /wp-admin. If a database upgrade is needed, WordPress will offer you a link to wp-admin/upgrade.php. Follow it.
  9. Reactivate your plugins, one at a time if you want to catch a conflict.
  10. Clear your cache again so visitors get the new version.

Stop it happening again

A failed update is almost always an interrupted update. Something stopped PHP mid-copy, and WordPress never reached the line that removes the file. Four things cause most of it. PHP ran out of time. A large update on a slow disk can exceed the host’s max_execution_time. Ask your host to raise it, or update over SSH where the web server’s request timeout does not apply. PHP ran out of memory. Unzipping and copying core needs headroom. If your host caps memory low, updates fail intermittently and unpredictably. File permissions blocked the copy. If the web server user cannot write to wp-admin and wp-includes, WordPress gets partway and stops. Your host can confirm the correct owner and mode for your setup. The tab got closed. Updates run in the browser request. Closing the tab or losing connection mid-update leaves the file behind exactly as a timeout does. Beyond that, two habits keep this rare. Update one thing at a time rather than ticking every box on the Updates screen at once, so a failure tells you what failed. And keep unmaintained code off the site: a theme or plugin that no longer gets releases will keep breaking on each new WordPress and PHP version, which is why we mark ours as retired rather than leave them looking current, as with Trope. If the thing that keeps failing is a specific premium theme, its own installer is often the culprit, which is the case we work through in Divi theme installation failed.

The short version

Delete .maintenance from your site root, clear your caches, and run the update again. That resolves the great majority of these, in under five minutes and without touching a core file. Only if the file is genuinely absent and the site is still broken do you need the manual reinstall, and even then the official steps above will get you there safely as long as you leave wp-content alone.