Why Is My WordPress Site Stuck in Maintenance Mode? A Troubleshooting Walkthrough

Seeing the “Briefly unavailable for scheduled maintenance. Check back in a minute.” banner on a live site is frustrating, especially when visitors start to drop off. The message usually appears after a failed update, but the underlying reasons can vary from file‑system glitches to caching quirks. This article breaks down the typical symptoms, pinpoints the most common causes, walks you through a systematic diagnostic checklist, and provides concrete fixes you can apply without a full reinstall.

Typical Symptoms of a Stuck Maintenance Mode

Front‑end banner that never disappears

The classic gray banner with the text “Briefly unavailable for scheduled maintenance. Check back in a minute.” remains on every page, even after waiting several minutes.

HTTP 500 or 503 errors

Some sites return a generic server error instead of the banner, especially when the .maintenance file is corrupted or the server’s PHP handler aborts.

Stalled plugin or theme updates

When you click “Update now” in the dashboard, the progress bar spins forever, and the update never completes.

Admin dashboard inaccessible

Occasionally the wp-admin area redirects to the maintenance page, preventing any further configuration.

Common Causes Behind a Persistent Maintenance Mode

Incomplete core, plugin, or theme update

WordPress creates a temporary .maintenance file at the root of the site during any update. If the process is interrupted—by a timeout, lost connection, or server reboot—the file remains, forcing WordPress to think the update is still in progress.

Incorrect file permissions

When the web server cannot delete the .maintenance file (e.g., it’s owned by root instead of the www-data user), the banner stays visible.

Corrupted .maintenance file

A malformed PHP snippet inside the file can trigger a 500 error instead of the friendly banner.

Stale server‑side cache

Reverse proxies (Varnish, Nginx fastcgi_cache) or CDN edge nodes may serve a cached copy of the maintenance page long after the file has been removed.

Plugin or theme that aborts the update process

Security or backup plugins sometimes lock the filesystem during their own operations, causing the WordPress updater to time out.

Diagnostic Checklist – Find the Root Cause Quickly

1. Verify the existence of .maintenance

Connect via SSH or SFTP and run:

ls -la .maintenance

If the file is present, note its owner and timestamp.

2. Inspect the file’s contents

Open it with a text editor. A healthy file looks like:

<?php
$upgrading = true;
?>

Anything else suggests corruption.

3. Check the wp-content/upgrade folder

Leftover update packages can block the cleanup routine. List its size:

du -sh wp-content/upgrade

Large or many files indicate an incomplete update.

4. Review server error logs

Tail the PHP or Nginx error log for the last 30 minutes:

tail -n 30 /var/log/nginx/error.log

Look for “permission denied” or “cannot delete .maintenance”.

5. Confirm file‑system permissions

The web‑user (often www-data or apache) must have write access to the site root:

stat -c "%U %A" .maintenance

Typical permissions: www-data rw-r--r--. Adjust with chown or chmod if needed.

6. Test cache layers

Purge any reverse‑proxy cache (e.g., varnishadm ban.url .) and purge CDN edges via the provider’s dashboard. Then reload the site.

7. Temporarily disable plugins

If you cannot access the admin UI, rename the wp-content/plugins directory:

mv wp-content/plugins wp-content/plugins.off

Refresh the site; if the banner disappears, a plugin is the culprit.

Step‑by‑Step Fixes

Remove the stray .maintenance file

Assuming you have confirmed the file is the problem, delete it:

rm -f .maintenance

Immediately refresh the front‑end. If the site loads, the issue is resolved.

Correct ownership and permissions

Set the correct owner (replace www-data with your web user):

chown www-data:www-data .maintenance
chmod 644 .maintenance

Repeat for the site root if other files show similar problems.

Clean up an incomplete upgrade folder

Remove leftover packages safely:

rm -rf wp-content/upgrade/*

Then run the update again, preferably via WP‑CLI to avoid browser timeouts:

wp core update

Re‑run the update with WP‑CLI

WP‑CLI bypasses the PHP timeout limits that often cause the maintenance file to linger. Example commands:

wp plugin update --all
wp theme update --all
wp core update

Each command automatically removes the .maintenance file on success.

Clear server‑side and CDN caches

After deleting the file, purge any caching layers you identified earlier. For Nginx fastcgi_cache:

rm -rf /var/cache/nginx/*

Then restart the service:

systemctl reload nginx

Use a stable hosting environment for smoother updates

If you repeatedly encounter update interruptions, consider moving to a platform that automates core updates and provides reliable file‑system permissions out of the box. You can rely on WordPress Hosting to streamline your deployment, keep the environment patched, and reduce the likelihood of a stuck maintenance mode.

Re‑install core files as a last resort

Download the latest WordPress zip from wordpress.org, extract it locally, and overwrite the wp-includes and wp-admin directories on the server. Do not replace wp-content or wp-config.php. This restores any missing core files that might be causing the updater to fail.

Quick tip: Always create a full site backup (files + database) before deleting core files or running bulk updates. A snapshot lets you roll back instantly if something goes wrong.

Warning: Never edit WordPress core files directly on a live site. Changes will be overwritten on the next automatic update, and they can also trigger the maintenance mode loop.

Preventing Future Maintenance Mode Hang‑Ups

• Schedule updates during low‑traffic windows. Use a cron job to trigger WP‑CLI updates at night.
• Enable automatic core updates. Add define('WP_AUTO_UPDATE_CORE', true); to wp-config.php if you’re comfortable with hands‑off patches.
• Monitor disk space. Low storage can abort the upgrade process; keep at least 20 % free.
• Use a staging environment. Test major plugin or theme upgrades on a clone before pushing to production.
• Implement health checks. Tools like wp health-check can alert you to permission mismatches before they cause trouble.

Conclusion

A WordPress site stuck in maintenance mode is almost always a file‑system or caching issue that can be resolved with a few targeted commands. By systematically checking for the .maintenance file, verifying permissions, cleaning up incomplete upgrade data, and clearing caches, you can restore normal operation without a full reinstall. For long‑term stability, consider a managed WordPress hosting solution that automates updates and enforces proper permissions, reducing the risk of future interruptions.