WordPress Maintenance Mode: How It Works

WordPress maintenance mode is a short-lived safeguard used during core updates. WordPress creates a .maintenance file, serves a temporary 503 response while files are changing, and removes the file when the update finishes. If an update stops unexpectedly, understanding that file is the fastest way to distinguish a stale flag from an incomplete update.

How the Native Maintenance File Works

The .maintenance file sits in the WordPress root directory, beside wp-config.php. During a core automatic update, WordPress writes a small PHP file containing an upgrade timestamp. Its contents are equivalent to:

<?php $upgrading = time(); ?>

WordPress checks for this file early in the request, before most of the application loads. On a single-site installation, if the file exists and $upgrading is less than 10 minutes old, WordPress stops normal loading. It returns HTTP status 503, sends a Retry-After header, and displays the familiar “Briefly unavailable for scheduled maintenance” response.

Once the recorded timestamp is at least 10 minutes old, WordPress ignores the file and continues loading. This automatic expiry is a safeguard against a permanently unavailable site after an interrupted update. It also means the native mechanism is unsuitable for a coming-soon page that must remain active for hours or days.

On current WordPress core, the root-file check is not excluded on Multisite. Because a network shares one WordPress root, the file is not a site-by-site maintenance toggle; verify network-wide effects before using it. Older guidance that says Multisite always skips .maintenance does not match the current core check.

The default response is intentionally minimal. A site owner can add wp-content/maintenance.php to replace the page shown while a valid .maintenance file is active. The custom file is loaded during the early maintenance check, so it should be self-contained, fast, and independent of plugins, the active theme, and database-dependent WordPress functions that may not be available.

Activate Maintenance Mode with WP-CLI

WP-CLI includes a bundled wp maintenance-mode command. Its subcommands create, inspect, and remove the same native file:

wp maintenance-mode activate
wp maintenance-mode status
wp maintenance-mode deactivate

Run these commands from the WordPress root or provide the correct --path global parameter. status reports whether WP-CLI sees maintenance mode as active, and deactivate removes the file.

The $upgrading value is written when activation occurs. It does not continuously refresh. WordPress therefore starts ignoring that file after about 10 minutes unless another process updates or recreates it. Native activation works well for a short deployment in which you are actively replacing files or applying a database change. It is not a persistent toggle for a site launch scheduled several days later.

A simple short deployment sequence is:

wp maintenance-mode activate
wp core update
wp plugin update --all
wp maintenance-mode deactivate

Do not copy that sequence blindly into production automation. Confirm that the update commands, filesystem permissions, backup state, and rollback plan fit the site. A shell that exits on the first failing command can leave the deactivation step unrun, although the 10-minute WordPress expiry still limits the visible maintenance response.

Fix a Site Stuck in Maintenance Mode

An interrupted core or plugin update is the usual cause of a leftover .maintenance file. A dropped SSH connection, PHP timeout, terminated process, container restart, or manually killed command can stop the normal cleanup step.

Most single-site installations recover visibly without intervention after the timestamp becomes 10 minutes old. The file may still exist on disk, but WordPress ignores it. If the maintenance response continues beyond that window, first make sure you are not seeing a cached copy at a CDN, reverse proxy, or browser and that another update process is not recreating the file.

When the page must be cleared immediately, remove the root file over SSH:

rm .maintenance

Use that command only after confirming the current directory is the intended WordPress root and no update is still writing files. Through SFTP or a hosting file manager, enable hidden-file display if .maintenance is not visible.

If WP-CLI can bootstrap the installation, use the supported command instead:

wp maintenance-mode deactivate

Clearing the flag restores request processing; it does not prove the interrupted update completed. Check the installed versions:

wp core version
wp plugin list
wp theme list

Compare those results with the versions you intended to deploy. Open the front end and administration area, inspect PHP logs, and verify that the database upgrade completed if the release required one. A partial plugin directory or mismatched core files can cause fatal errors after maintenance mode disappears.

For core integrity, WP-CLI can compare core files against official checksums:

wp core verify-checksums

That check covers WordPress core, not arbitrary plugin or theme files. Reinstall a damaged component from a trusted source or restore it from a known-good backup rather than editing around a partial update.

Built-In Mode Versus a Plugin

WordPress core does not provide a persistent administration-screen toggle for an indefinite maintenance or coming-soon page. The built-in file is transient, tied to update operations, and constrained by the 10-minute timestamp.

A WordPress maintenance mode plugin is the practical choice when planned downtime needs:

• A deliberate on/off control that persists indefinitely.
• A branded message or launch countdown.
• IP-, role-, or login-based bypass for administrators and testers.
• Email capture or other page features.
• Activation without shell or filesystem access.

Such plugins commonly intercept front-end requests through a hook such as template_redirect and decide whether to serve the maintenance response. The exact behavior varies by plugin, so verify status codes, caching, bypass rules, REST API behavior, scheduled tasks, and login access before enabling it.

Use the built-in mechanism for short, active update windows. Use a plugin for a long-running, customizable state that a site owner deliberately controls. A plugin also adds code and configuration that must itself be maintained, so avoid installing one when a brief native update window is all that is needed.

Plan the Update Window

Take or verify a restorable backup before changing core, plugins, or themes. Test high-risk updates in staging when available, and keep maintenance windows as short as the change permits. The broader WordPress maintenance process should include version checks, backups, testing, and rollback rather than treating the maintenance page as the safety mechanism.

Cost planning matters when deciding whether staff will manage these steps or a provider will own them. The WordPress maintenance cost breakdown explains which services are commonly bundled and which are billed separately.

Nova handles WordPress core and plugin updates as part of its managed WordPress hosting plans. Customers do not need to manually babysit .maintenance during their own update windows, while the underlying update still needs the same careful validation.

FAQ

Why did WordPress enter maintenance mode?

Core normally creates .maintenance while an update changes files. If the message remains visible, the update may have been interrupted before cleanup.

Will WordPress leave maintenance mode automatically?

On a single-site installation, WordPress ignores the file once its recorded timestamp is at least 10 minutes old. That does not repair files or database changes left incomplete by an interrupted update.

Where is the maintenance file?

It is named .maintenance and resides in the WordPress root beside wp-config.php. Because the name begins with a dot, some file tools hide it by default.

Can I customize the built-in maintenance page?

Yes. A self-contained wp-content/maintenance.php file replaces the default response while native maintenance mode is active.