Skip to content

Recovering a WordPress site from a failed automatic update on cPanel

A working playbook for recovering a WordPress site after a failed automatic update on cPanel — diagnosing the state, completing or rolling back the update, and preventing the next one.

Automatic updates work most of the time. The times they don’t, they fail in ways that are harder to recover from than a manual update because nobody was watching the screen, the failure happened at 2 a.m., and the site spent six hours half-updated before anyone noticed. The recovery is mechanically straightforward; the operational lessons matter more.

What’s happening

WordPress’s auto-update process: write .maintenance, download new files to wp-content/upgrade/, copy over the live files, run database upgrades, delete .maintenance. If any step fails partway through (PHP timeout, disk full, fatal error during the new code’s first execution), you can end up with: some files updated and some not, .maintenance still present, partial database schema, half-activated plugins. Symptoms range from “stuck maintenance message” through “white screen” to “critical error” depending on where it failed.

How to verify

Determine where the update is:

ls -la ~/public_html/.maintenance
ls -la ~/public_html/wp-content/upgrade/ 2>/dev/null
wp core version
wp core verify-checksums 2>&1 | head
wp plugin verify-checksums --all 2>&1 | head
wp db check

The presence of wp-content/upgrade/<plugin-name>/ directories means an update was unpacking when it died. The state of verify-checksums tells you whether the file copy completed.

The fix

  1. Remove the maintenance file so the site returns:

    rm ~/public_html/.maintenance
  2. Determine whether to complete the update or roll back. The decision depends on whether you can identify which version was being installed and whether you have a clean backup from before the attempt:

    • Complete: if files appear mostly new, the update was nearly finished. Re-run via WP-CLI to clean up:

      wp core update --force
      wp core update-db
      wp plugin update --all

      --force makes WordPress download core again regardless of version comparison, which fixes partial copies.

    • Roll back: if you have a backup from immediately before the update, restoring it is faster and safer:

      wp db import ~/backup-pre-update.sql
      tar -xzf ~/backup-pre-update-files.tar.gz -C ~/public_html
  3. Audit what’s left in wp-content/upgrade/. Those directories are work in progress; if no update is currently running, they’re junk:

    rm -rf ~/public_html/wp-content/upgrade/*
  4. Re-verify checksums after either path:

    wp core verify-checksums
    wp plugin verify-checksums --all

    No mismatches means the file state is consistent.

  5. Smoke test. Homepage, admin login, one content page, one form submission. Confirm the site is back to working.

  6. Identify why the update failed. Read the PHP error log for the time window:

    grep -i 'fatal\|memory\|timeout\|allowed memory' ~/public_html/error_log | tail -30

    Common causes: PHP memory limit exceeded during the update (raise WP_MEMORY_LIMIT), max_execution_time exceeded (move updates to WP-CLI), disk full (clean up old backups, expand disk).

  7. Decide on the auto-update policy going forward. Three reasonable choices:

    • Disable auto-update entirely, run updates manually via WP-CLI on a schedule. Most reliable, most operator effort.
    • Auto-update minor versions only, manual for major. Default WordPress behavior. Reasonable for low-stakes sites.
    • Auto-update via WP Toolkit’s Smart Update with clone-and-test. Combines automation with a safety net. Costs licensing but worth it on a fleet.
  8. Add basic monitoring. A 60-second check that the homepage returns HTTP 200 catches a stuck-maintenance situation in a minute, not six hours. Stack Harbor handles update flow and monitoring under enterprise WordPress operations.