WordPress: escape the “Database Update Required” loop

Understand why updated files are not enough

WordPress reports that its files were updated, then displays “Database Update Required” or a request to update the database. After confirmation, the same screen returns. Sometimes the button leads to a critical error before returning to the start. The problem is therefore not necessarily the file download.

Core compares the database revision expected by its files with the revision recorded for the site. The upgrade adapts tables and some data when necessary. This revision number is not the public WordPress version number: two public releases may share the same schema state.

The goal is a consistent installation: the correct files use the correct database, the necessary procedure completes, and normal functions remain accessible. Hiding the screen or changing a number to satisfy the comparison does not perform this upgrade. If an error interrupts the operation, first record that error instead of endlessly pressing the button.

Identify the core message and correct environment

This guide addresses the WordPress core message on a self-hosted installation. A plugin may offer its own data update: the product name, screen, and procedure are then different. Do not run a core upgrade to automatically address every notification containing the word “database.”

Record the screen address, exact title, and what happened after the single attempt already made. A maintenance screen, a lock saying another update is in progress, a MySQL connection rejection, or a persistent critical error require distinct diagnoses, even if they occur during the same intervention.

1. Confirm the domain, HTTPS protocol, and affected site before logging in.
2. Note the target WordPress version and the method used to replace its files.
3. Identify whether the site belongs to a multisite network or a service managing updates on your behalf.
4. Keep the attempt time and final message. On WordPress.com or a managed platform, use the service’s maintenance process rather than a command intended for another environment.

Prepare a backup that allows a real rollback

The upgrade may write to the database. Before another attempt, prepare database and file backups representing the same state, with their date and restoration method. An archive containing only media cannot restore the old tables; an SQL export alone does not preserve the plugin versions that will use those data.

If files have already been replaced, also preserve the backup made before that update. A new snapshot of the blocked state is useful for diagnosis, but does not automatically become a working-state backup. Check which file and data sets can be restored together.

Choose a maintenance window and avoid concurrent writes during any restoration. For a shop or a site receiving requests, prepare an appropriate pause: restoring an older state may lose operations received since then. On a private copy, disable emails, payments, and external tasks. Finally, have the host confirm the object-cache scope before execution: an actual core migration calls its flush operation. On shared infrastructure, a key prefix alone does not guarantee that this flush is limited to the site. If this scope is not controlled, have an isolated copy or an intervention by the service administrator prepared.

Verify the target before modifying the database

An incomplete migration or deployment may cause recent files to use an old database, or a copy to use the production database. In the hosting panel, record the domain root. Then privately inspect the active configuration to confirm the database name and table prefix, without changing these values to try several targets.

If a deployment tool manages the site, compare the intended release with the one actually installed on every server. A request reaching an old server may produce a different result from the next one. The number in one file does not guarantee that all core files were replaced correctly.

With WP-CLI already available, the check below compares core files with official checksums. Replace the path, VERSION_CIBLE, and LOCALE with the verified release’s version and language, for example the locale actually used rather than the browser’s. This command contacts WordPress.org; a network failure does not establish corruption. It does not repair files or check your content. If discrepancies are confirmed, have the coherent release completed before running its database upgrade.

wp core verify-checksums --path="/chemin/vers/wordpress" --version=VERSION_CIBLE --locale=LOCALE

Complete the upgrade through the native screen

This approach is suitable for the person with site maintenance access once files and target are confirmed and the backup is ready. Open the affected installation’s wp-admin/upgrade.php path, without a parameter after the filename. Do not reuse an address containing ?step=1: that step triggers the upgrade instead of merely displaying the proposal. If core is in a subdirectory, retain that actual path; the homepage address may differ from the WordPress files’ address.

The screen may say that no update is necessary. In that case, force nothing: continue to administration validation and investigation of a stale display. If it requests an update, the button starts a write operation; it is not a read-only check.

1. Open the upgrade address on the confirmed domain in a single working tab.
2. If the request is present, click the WordPress database update button once.
3. Let the request finish without starting a second operation in another tab.
4. If confirmation appears, use Continue, then open administration directly.
5. If an error, blank page, or timeout appears, note the time and stop retrying. The log and version check should guide the next steps.

Compare revisions with WP-CLI

The terminal alternative is appropriate if WP-CLI is already installed and you control access to the correct environment. Run the three commands below separately, with the same actual path. The first displays file information, the second reads the option as WordPress sees it, possibly from the object cache, and the third compares the value read directly from the database with the expected revision without performing the requested upgrade.

The --dry-run mode is a comparison, not a full rehearsal of every future SQL query. Its result therefore does not prove that permissions or resources will allow the actual operation. Commands loading WordPress may also load plugins and their code; use a controlled copy for investigation and do not add a global workaround at the first error message.

Compare the expected revision in the extra information with the values reported by the other two commands. If the option reading and direct comparison differ on the same target, have the object cache examined. If the direct comparison expects no change but the browser loops, check the web target and cache layers before any write.

If the stored revision is higher than the one expected by the files, stop: an old release may have been put back onto an already-migrated database. The upgrade command is not a procedure for returning to an old schema. If the database is behind, keep both revisions and prepare execution only once the target, backups, and release are confirmed.

wp core version --extra --path="/chemin/vers/wordpress"
wp option get db_version --path="/chemin/vers/wordpress"
wp core update-db --dry-run --path="/chemin/vers/wordpress"

Run the terminal procedure on a single site

For a single site, the command below runs the upgrade procedure for core already present. It does not download a new WordPress version or replace an incomplete release. Replace the example path with the one you checked and use the designated technical account, without a password in the command.

Do not run this operation simultaneously with the browser button. If a terminal disconnects, check the operation and database state before retrying. A success message is useful evidence to retain, but does not certify every SQL transformation: WP-CLI may suppress database error display during this call. Checking logs and site functions remains necessary even if the final revision looks correct.

1. Confirm backup availability and the maintenance window.
2. Run the command once and keep its output in a private location.
3. Then rerun only the previous section’s --dry-run comparison to check that no upgrade is announced.
4. Open administration in the browser and perform the planned functional checks.
5. If the screen returns or an error appears, move to targeted diagnosis without manually changing the revision number.

wp core update-db --path="/chemin/vers/wordpress"

Read the error preventing completion

In the hosting panel, open the PHP log or domain error log and search for the exact failure time. Keep a few lines around the first significant message. A fatal error naming a plugin file, a memory limit, and an SQL rejection do not require the same fix.

For an SQL error, record the rejected operation and table name, redacting them if necessary. An upgrade may create or change table structures: being able to publish a post does not prove that the MySQL account has the permissions needed for this operation. The database administrator must check the missing privilege on the correct database; granting every privilege on the entire server is not a targeted fix.

If no log is accessible, request the one for the relevant domain and time window. The maintainer can prepare temporary WordPress diagnostics with a private log, without displaying errors to visitors, then remove them after collection. Do not make a log file publicly downloadable. Fix the established cause on a copy before another attempt: deactivating every plugin or raising every limit would destroy the diagnosis’s precision.

Distinguish a stale read from an unfinished migration

If the terminal considers the database current but the web screen still requests an update, first check that both paths use the same directory, configuration, and database. A command run on the validation copy does not describe production. With multiple servers, also check that all use files from the same release.

The object cache retains data used by WordPress; the page cache retains an HTML response. These are two different layers. An old administration-screen response must not be served as a public page, and a stale metadata reading is not fixed by deleting every visitor’s cookies.

Have the maintainer compare the revision stored in the correct database with the one read through the web path, then check the scope of the cache actually involved. If invalidation is necessary, use the mechanism documented for this installation. Do not run a global cache-service purge on shared infrastructure. When migration is necessary, core itself calls the object-cache flush. However, it may return immediately if its direct database reading already shows the correct revision: that pass then guarantees no flush. Therefore have the stale read corrected through the mechanism intended for this site, without repeating the migration or purging the entire shared service.

Another cache stores compiled PHP code: OPcache. After a release, if the web process still uses old code, browser results may differ from terminal results. Ask the host to check that the domain process has picked up the files. Invalidation or reloading must follow its procedure and scope; do not add a public reset script.

Define the scope before a multisite upgrade

A network shares core files, but each subsite has data and a revision to account for. The extra version information from wp core version --extra describes the revision expected by the files; it does not replace reading each subsite’s own option.

The --network option of wp core update-db extends the operation to network sites. Do not add it to repair the one site whose screen you see faster: its scope is broader and requires corresponding preparation. In an installation with multiple networks, the URL context must also be defined according to the administrator’s procedure.

To inspect a subsite, the maintainer can use wp option get db_version --url=https://sous-site.example --path="/chemin/vers/wordpress", replacing the address with the actual target. This read does not upgrade its tables. Then prepare an inventory of affected sites, a network backup, and an appropriate window before any expanded execution. Keep a per-site report, because an overall result does not remove the need to identify a failing subsite.

Do not replace migration with a number or a repair

Do not change either the db_version value in the database or the expected variable in wp-includes/version.php to make the request disappear. The comparison could then appear satisfied without the necessary transformations taking place. At the next intervention, diagnosis would also be obscured by a declared state differing from the actual state.

Table repair and schema upgrade have distinct goals. A repair option does not replace core’s migration procedure. Do not enable WP_ALLOW_REPAIR simply because the screen returns; look for a message establishing corruption before choosing an appropriate repair procedure.

A new plugin does not directly resolve this step preceding administration access. Installing a tool at this point may be impossible and adds files without fixing the schema. Core and WP-CLI provide the two approaches needed here. Plugin-specific migrations must subsequently be handled according to their documentation once access is restored, with backups appropriate to their effects.

Validate completion of the intervention

The screen disappearing is necessary but insufficient. Return to the same account, domain, and functions used before the update. Public pages may still display from a cache while part of administration fails. Therefore check both paths.

On a copy, saving test content checks writing without creating a real publication. In production, use an internal operation agreed with the administrator, and avoid triggering a payment or email merely for this check. Verification should cover affected functions, not a series of unrelated actions.

1. Reopen wp-admin/upgrade.php without parameters on the checked installation and verify that no upgrade is requested.
2. If using WP-CLI, confirm that the comparison no longer expects an upgrade.
3. Open the dashboard, a content list, the editor, and important public pages.
4. Reread the log for this period and check that no new SQL or PHP failure related to the intervention appears.
5. Record versions, the retained backup, and results before ending maintenance.

Restore a coherent set if recovery fails

If the upgrade remains impossible after identifying the cause, prepare a return to the last usable state with the site owner. Simply copying old files onto an already-modified database is not a complete rollback. Determine which files and database snapshot belong to the same state and what has happened since.

Before restoration, keep a private snapshot of the current state and inventory useful new writes: content, registrations, or orders, depending on the site. The choice between restoration, correction, and recovery of these data must be explicit. Do not reimport an old database over production assuming nobody worked during the failure.

Restore the planned set according to the backup procedure, check the domain and connections, then repeat functional checks. Record the failure cause, first error message, and affected release. For the next attempt, validate the same change on a representative copy, check required privileges, and plan migration completion as part of deployment. This avoids treating file replacement as the last step while the database is still waiting for its update.

Interpret the three revisions without changing their values

Teaching example with fictional numbers: files expect revision 60000, the database contains 59900, and WordPress also reads 59900. After confirming the correct environment, this case warrants preparing the upgrade; the numbers must not be copied into your database.

Second case: files and the direct database read indicate 60000, but the option read by WordPress indicates 59900. The object cache becomes a lead, provided that all three readings concern exactly the same installation. Repeating an already-unnecessary migration is not a guaranteed way to invalidate that reading.

Third case: the database is at 60000 but the files expect only 59900. An old release may have been restored onto a newer database. Stop upgrade attempts and restore a coherent combination of files and data according to the deployment plan.

In your record, replace these fictional values with the actual outputs and add the path, subsite URL, server, and time. In multisite, use one row per affected subsite. A numerical comparison helps beginners explain the block and maintainers choose between migration, cache, and release; no table-repair tool is needed to read this difference.