A WordPress Site Stuck on the Maintenance Message

One line instead of the website

On Monday morning the office manager of a property management company opens the website to a single line where the home page should be: briefly unavailable for scheduled maintenance, check back in a minute.

Tenants have been seeing it since some time overnight. Two have emailed to ask how to report a repair, and an owner has phoned about the monthly statements posted there.

Nobody at the office scheduled any maintenance. The line comes from WordPress itself, and it means an update began and never properly finished.

Where the line comes from

When WordPress updates itself, or updates plugins and themes that are in use, it first writes a small file named .maintenance into the folder that holds the site. While that file is there, every page shows the one line.

The notice protects visitors from a site whose files are being swapped, which would otherwise show errors or half-loaded pages for a minute or two.

When the update finishes, WordPress deletes the file and the site returns. If the update never reaches its last step, the file stays where it was.

How an update stops halfway

Updates download files, unpack them and copy them over the old ones. Any of these can stop partway:

• A time limit on the server, which ends any process that runs too long.
• A memory limit, reached while unpacking a large plugin or theme.
• A lost connection to the server that supplies the update.
• Full storage, leaving no room for the new copy.
• File permissions that let WordPress delete an old file but not write a new one.

A slow, shared server makes the first two likelier, and so does updating many plugins in one go, since they all run in the same process.

When the notice outlasts the update

WordPress is built to ignore a leftover notice file once it is about ten minutes old, so a stalled update alone should hide the site only briefly.

A notice still showing hours later has something renewing it, such as an update tool that keeps retrying the same failed step, or it comes from a separate maintenance add-on.

Either way, the file is the place to start, and the half-finished update behind it is the real problem.

Clearing the notice

Reach the site's files with an FTP program, or through the host's control panel, and open the folder that holds WordPress, where wp-config.php usually sits.

The file name begins with a dot, which many file managers hide. Turn on the option to show hidden files, find .maintenance, and delete it.

Reload the site. If the notice is gone, move straight on to checking the update. If it is not, ask the host what else is writing it.

A worked example

A legal transcription service with a small office and a team of typists working from home turns recordings from law offices into transcripts. Clients upload audio files through a page on its WordPress site.

One morning the office manager updated six plugins at once. The host's server was busy, the downloads dragged, and the server's time limit stopped the process partway through the fourth.

A law office called within minutes, unable to upload a recording. The notice file was deleted straight away and the site returned, but the upload page still failed.

The plugin behind it had been removed before the update stalled and never replaced. It was reinstalled from a clean copy at the same version, and a test file went through.

Updates now run on Tuesday afternoons, one plugin at a time, after a fresh backup, by someone who stays to test the upload page. A failed update is noticed in minutes, with a way back ready.

What the update left half done

Go to the Updates screen in the dashboard. Anything still listed as waiting did not finish, and WordPress itself can be reinstalled there at the current version.

Then open the Plugins screen. A plugin removed partway through its update is switched off, with a message that its file does not exist. Reinstall it from a clean copy of the same version.

Finally, test what the business depends on: forms, payments, logins, uploads. Ask the host for the error log if anything misbehaves, since it records what failed and where.

Updates need someone watching

Most updates finish cleanly. The trouble is that the rare failure happens at a time nobody chose, and a site that fails at night stays broken until someone looks.

Since version 3.7, released last October, WordPress installs minor and security releases on its own and emails the site's administrator about each one. Someone should be reading those emails.

Plugin and theme updates are better run by a person, one at a time, at an hour when that person can test the site straight afterwards and act if something breaks.

A backup before every update

An update that fails badly may leave files that cannot simply be reinstalled, or a database half converted to a new format. A backup taken minutes before is the way back.

The backup needs both parts of the site: the files and the database. A nightly backup at the host is a safety net, but it misses everything changed since last night.

Now and then, restore a backup to a test copy. Until one has been restored, nobody knows whether the backups can be trusted.

The counter-case

Brochure sites with a standard theme and two or three well-kept plugins may update for years without a single stall. Their updates are small and finish quickly.

For a site like that, a notice that appears during an update and clears within minutes is WordPress working as designed, not a fault.

Even so, someone should know when updates run and look at the site afterwards. The day one does fail, the business hears about it from that person, not from a tenant.

A safer routine for updates

1. Take a backup of the files and the database.
2. Choose a quiet hour when someone can stay and test.
3. Update one plugin at a time, not all at once.
4. Check the Plugins screen for anything switched off.
5. Test the forms, logins and payments afterwards.
6. Know where .maintenance lives and how to delete it.
7. Read the update emails WordPress sends.

Step two is what turns a failed update into a short delay. Someone watching sees the notice stay too long, deletes the file and repairs the plugin before customers notice.

Another one-line message that replaces a whole WordPress site, and what to ask the host about it, is explained in the database connection error on a WordPress site.

Frequently asked questions

West Coast Media Solutions Inc. provides web design, web development, hosting, digital marketing, and business consulting to organisations across Canada, drawing on more than twenty-five years in the field.