When a WordPress update fails, the site can stay stuck behind the “Briefly unavailable for scheduled maintenance” screen. Visitors see a white page or a maintenance message, and the admin area may be inaccessible. The usual cause is a leftover .maintenance file in the WordPress document root.

Quick diagnosis

Check if the .maintenance file exists:

ls -la .maintenance

If it exists and no update process is still running, remove it:

rm .maintenance

Reload the site. If it comes back, the update process is either still running or failing repeatedly. Do not just keep deleting the file — find the root cause.

Why it happens

WordPress creates .maintenance before running core, plugin, or theme updates. The file contains a timestamp:

<?php $upgrading = 1717718400; ?>

WordPress removes .maintenance when the update completes. If the update process is killed, times out, or hits a fatal error, the file stays behind.

Common triggers:

  • PHP timeout — max_execution_time is too low for a large update
  • Memory exhaustion — Plugin or theme update exceeds memory limit
  • Disk full — No space to extract update archives
  • Permission issue — Web server cannot write to plugin or theme directories
  • Plugin conflict — A plugin hooks into the update process and crashes
  • Multiple concurrent updates — Two admin sessions trigger updates at the same time

Check the basics before retrying

Run these diagnostics before attempting another update:

Disk space

df -h
df -i

WordPress needs space for temporary files and extracted archives. Less than 100 MB free is risky.

File ownership

ls -la wp-content
ls -la wp-content/plugins
ls -la wp-content/themes

Files should be owned by the web server user (www-data, nginx, apache). If ownership is mixed or root-owned, updates will fail.

PHP errors

Check the PHP error log:

grep -i 'fatal\|error' /var/log/php*-fpm.log | tail -20
# Or depending on your setup:
grep -i 'fatal' /var/log/nginx/*.log | tail -20

Look for memory errors, require/include failures, or class/function redeclaration errors from plugin conflicts.

Active update processes

Check if WordPress is still running an update:

wp option get core_updater.lock
wp option get auto_updater.lock

If these options exist, an update may be in progress. Wait a few minutes and check again. If they persist for more than 10 minutes, the update process likely crashed.

Clear stuck locks:

wp option delete core_updater.lock
wp option delete auto_updater.lock

Safer retry path

Via WP-CLI (preferred)

WP-CLI handles updates more reliably than the web interface:

# Update core first
wp core update --minor
wp core update-db

# Then plugins in small batches
wp plugin update --all --dry-run
wp plugin update --all

# Themes last
wp theme update --all

Via web admin (if WP-CLI unavailable)

  1. Take a full backup first
  2. Disable all caching plugins temporarily
  3. Update plugins one at a time, starting with the most critical
  4. Check the site after each update
  5. If the site goes into maintenance mode again, remove .maintenance and investigate the last plugin you tried

For business-critical sites

  • Take a backup
  • Clone to staging
  • Run all updates on staging first
  • Test thoroughly
  • Apply to production during a maintenance window with monitoring

Preventing recurrence

Increase resource limits

In wp-config.php:

define('WP_MEMORY_LIMIT', '256M');

In your PHP-FPM pool config:

php_admin_value[memory_limit] = 256M
php_admin_value[max_execution_time] = 300

Monitor disk space

Set up a simple cron job to alert when disk space drops below a threshold:

#!/bin/bash
THRESHOLD=90
USAGE=$(df / | tail -1 | awk '{print $5}' | sed 's/%//')
if [ "$USAGE" -gt "$THRESHOLD" ]; then
  echo "Disk usage at ${USAGE}% on $(hostname)" | mail -s "DISK ALERT" admin@example.com
fi

Stagger auto-updates

If you use automatic updates, ensure plugins with known conflicts are not updated simultaneously. Some managed hosts provide staggered update schedules.

When to stop and escalate

Stop retrying if:

  • The same update fails twice with the same error
  • You cannot identify the cause after checking logs
  • The site handles payments, memberships, or critical business functions
  • Multiple plugins fail simultaneously (suggests a server or PHP issue)

At this point:

  1. Clone the site to staging
  2. Debug the failure without time pressure
  3. Check for known conflicts in plugin changelogs
  4. Contact the plugin author or host support
  5. Plan a migration off problematic plugins if they repeatedly block updates

A stuck maintenance mode is usually a quick fix. A site that repeatedly gets stuck has a deeper problem that needs investigation before the next update window.