Stuck .maintenance mode prevents sites from starting

[dknauss]

Quick summary

It's easy for users to get a Studio site into a long-lasting white-screen maintenance mode lockout with this frustrating, inaccurate message displayed: "Briefly unavailable for scheduled maintenance. Check back in a minute." One way to reproduce this is to interrupt or abandon a long-running update after .maintenance has been created.

This lockout should clear up after ten minutes, but if the user tries stopping and restarting the site in Studio, they will find it no longer starts at all. Instead, another unhelpfully vague error message suggests the core install files may be incomplete or modified:

Checking for a .maintenance file would be a nice touch here, if only to give the end user a clearer description of why their site won't boot.

Steps to reproduce

1. Get stuck in maintenance mode. Browse away from many, long, active updates in the admin interface or add a dummy .maintenance file to the root folder for a WordPress instance running in Studio. Typically these contain a single line of PHP with a Unix timestamp indicating when the update/maintenance lock was created. <?php $upgrading = 1781739530; ?> Until 10+ minutes have passed since that timestamp, WordPress will display the maintenance mode WSOD.
2. Stop and restart the site in the Studio app. Studio will throw its own error message and fail to start.

What you expected to happen

The site should load in maintenance mode, at worst. Ideally, Studio should detect the .maintenance file and possibly report the timestamp, note when it will clear up on its own, and offer to clear it immediately if the user chooses.

What actually happened

Sooner or later, everyone hits this WSOD.

Impact

Some (< 50%)

Available workarounds?

Yes, difficult to implement

Platform

Mac Silicon

Logs or notes

No response

[dknauss]

I looked through Studio's startup path a bit more. I don't see any Studio-side check for .maintenance right now.

What seems to be happening:

• WordPress checks maintenance mode very early in wp-settings.php, before Studio's MU-plugin/admin API can load.
• During startup, Studio makes an internal request to /?studio-admin-api to set/check admin credentials.
• If .maintenance is active, Core returns the maintenance-mode 503 instead of letting that request reach Studio's admin API.
• Studio then treats that as an unclassified startup failure, so the UI falls through to the generic “verify standard WordPress installation files” message.

A safer behavior might be:

1. When startup fails, check the site root for .maintenance.
2. Parse the $upgrading Unix timestamp if present.
3. If it is younger than 10 minutes, explain that WordPress is still in maintenance mode and show when it should expire.
4. If it is older than 10 minutes, describe it as a stale maintenance lock and offer to remove it.
5. Avoid silently deleting a fresh .maintenance file, because updates may still be actively replacing plugin/theme/core files. Clearing the lock too early could expose a partially updated site and trigger fatals or mixed old/new code paths.

So the fix probably shouldn't be “always delete .maintenance on startup,” but rather detect it, explain it, and only offer cleanup when it is stale — or with a clear warning when it is still fresh.