How WordPress maintenance mode works

What maintenance mode is

WordPress maintenance mode is a built-in shutdown switch driven by a single file called .maintenance in the site root (the document root, next to wp-config.php). When that file exists, WordPress stops loading entirely and lets a tiny loader say "Briefly unavailable for scheduled maintenance. Check back in a minute." It does not run plugins, theme code, or the database. The mode is a safety door, not a feature: it exists so a half-updated set of files never serves garbage to visitors.

How it works

• During any core, plugin, or theme update, WordPress drops .maintenance before touching files and deletes it when the job finishes.
• The loader branch that powers the message checks the file with a small time guard: a very old file is treated as a leftover, so a crashed update fails loudly but never locks a site forever.
• The same mechanism is what plugins use under the hood when they offer a "maintenance mode" toggle: they create the file and typically serve HTTP 503 while it exists.
• An alternative people meet is a page from a caching or hosting plugin, which does not use the WordPress file at all; it templates an HTML page and sends 503 from its own option.

The difference matters when you need to get the site back. A core-injected .maintenance is yours to delete safely. A plugin-driven 503 lives in the plugin's own option, and deleting a file never turns it off.

How you enter and exit it

The common entries:

To take the auto mode off by hand, the only command you need:

rm /var/www/example.com/.maintenance

Then load the site. If it is a newly-started state, the mode lifts instantly. If the crash happened mid-update, the site might still be broken by a partial write, so follow the white-screen or plugin-isolation steps before claiming the fix.

Stuck in maintenance: the safe exit order

1. Verify the marker exists: ls -la in the docroot, looking for .maintenance.
2. Read its contents. A maintenance file usually holds the time the update started (a timestamp). If the timestamp is older than a few minutes, the update has clearly given up.
3. Delete the file, then retry the update from a stable connection so the auto path works again.
4. Check wp-content for a half-unzipped plugin and the debug.log for the fatal that aborted the write.
5. Clear the page cache, object cache, and CDN edge, because a cached page from while the mode was on sticks longer than the mode itself.
6. Deploy a monitoring alert on the exact phrase "Briefly unavailable" or "maintenance": if the site ever falls back into that state unattended, the alert catches it instead of the next visitor.

When to use it deliberately

If you are doing a release that touches files, it is safe to drop your own site-root .maintenance first and remove it after the release, so an unexpected restart of the build cannot serve mid-write output. The same file serves a manual maintenance window entirely: delete it only when the fix is complete, because the protection is exactly what you want during a fragile change.