WooCommerce database update required: what the notice means and how to finish it safely

The notice means WooCommerce's files are on a new version and its part of the database is still on the old one. The update it asks for brings WooCommerce's tables and stored settings up to the version of the code. The store stays open while the update waits and while it runs.

The safe order is to back up the database, start the update once, and let it finish in the background. Since WooCommerce 9.9 the update starts by itself once the plugin has been updated. On a current store the backup therefore has to come before the plugin update, and a notice with a button means the automatic start was switched off or did not work.

What the notice says

WooCommerce shows one of three messages in the same place, at the top of WordPress screens such as Dashboard and Plugins. Its own screens, such as Home and Orders, do not draw it.

The first message goes on: "The database update process runs in the background and may take a little while, so please be patient. Advanced users can alternatively update via WP CLI." Both routes are described below.

Where WP-Cron is switched off, the second message adds "Note: WP CRON has been disabled on your install which may prevent this update from completing." Its link then reads "You can manually run queued updates here." Take that line at its word. It is the first cause to check under "When it is stuck" below.

Why a current store may show no notice at all

Until WooCommerce 9.9 the notice with its button was the normal course. The release notes for 9.9, published in June 2025, say: "All stores as of 9.9 will now run database updates and migrations automatically in the background."

On 9.9 or later, WooCommerce queues the update on the first page load after the plugin's files change. It shows no notice before and none when it is done.

So "WooCommerce database update required", with its button, now means one of three things:

• The store runs a version older than 9.9.
• The automatic start was switched off. WooCommerce has a filter for that, woocommerce_enable_auto_update_db. A host, a developer or another plugin can set it.
• WooCommerce tried to queue the update and could not. It then falls back to the notice so that the update is not missed, and writes "There was an error scheduling database updates." to its log.

WooCommerce's own guide to updating still describes the notice and the button as what happens. The update is the same either way: the same tasks, in the same queue, with the same ways to get stuck.

Does the store keep working in the meantime?

Yes. The notice itself says the update runs in the background. Nothing in it closes the store, and pages are served while the tasks wait and while they run.

What the store lacks until then is whatever that release's update supplies. In recent releases the steps have included adding an index to a table, migrating a setting and adding rows to a lookup table. Neither the notice nor the documentation says what misbehaves if you wait, and it differs from release to release.

So do not leave it for days. Finish the update, then place a test order, as the WooCommerce maintenance routine describes. If the order does not go through, WooCommerce checkout not working has the checks.

Before it runs: back up the database

WooCommerce's guide says to back up the database and the wp-content folder before you update. WordPress's documentation says to back up "regularly, and always before an upgrade". The tool that starts this update by hand carries the same warning: "Please ensure you make sufficient backups before proceeding."

The reason is that the update changes tables and settings in place, and WooCommerce documents no undo for it. Its one documented way back to an earlier version starts with restoring "a database backup that matches the WooCommerce version you plan to install". Without that backup there is no way back.

On WooCommerce 9.9 or later, take the backup before you update the plugin. The database update is queued by the next page load, a visitor's included. A backup taken after the plugin update may be a copy of a database that is already being changed.

With WP-CLI, this writes the whole database to one file:

wp db export ~/before-woocommerce-update.sql

The ~/ puts the file in your home folder, outside the folder the site is served from. An export left inside the site's folder can be downloaded by anyone who guesses its name. How to use WP-CLI covers connecting and running a first command. How to schedule automatic WordPress backups covers the other ways to make a backup, and how to safely update WordPress has the rest of the routine around an update.

Write down the time of the backup. Every order placed after it is missing from it, which matters under "What not to do" below.

How the update runs

WooCommerce hands the update to Action Scheduler, the task queue that ships inside it. Each step of the update becomes one task, called an action:

• One action for each step, on the hook woocommerce_run_update_callback. Its arguments name the step, for example wc_update_1030_add_comments_date_type_index.
• One last action, woocommerce_update_db_to_current_version, which writes the new version number.
• All of them in one group, woocommerce-db-updates.

Action Scheduler's documentation names two things that start the queue: WP-Cron, at most once a minute, and page loads in the WordPress dashboard. Each run works through actions for up to 30 seconds and leaves the rest for the next run. How long the whole update takes depends on how many steps the release has and how much data each one goes through. WooCommerce gives no figure.

Where to watch it

Go to WooCommerce, then Status, then Scheduled Actions. The same screen is under Tools, then Scheduled Actions. Type woocommerce_run_update into the search box to list the steps. The notice's "View progress →" link opens the screen with that search made and set to Pending. The last action has a different name, so search for woocommerce_update_db_to_current_version to see it.

The columns are Hook, Status, Arguments, Group, Recurrence, Scheduled Date and Log. The links above the table filter by status.

How to tell that it has finished

The last action writes the database's version number. Read it, then read the plugin's version, and compare the two.

wp option get woocommerce_db_version

wp plugin get woocommerce --field=version

The update has finished when the first is the same as the second, or the same with a suffix. A plugin at 11.2.0 beside a database at 11.2.0-1 is finished: WooCommerce records the higher of the plugin's version and the number of its last update step. A database at 9.9.7 beside a plugin at 11.2.0 is not.

Without the command line, go to WooCommerce, then Status. The report has a "WooCommerce version" row, and under Database a "WooCommerce database version" row. Its help text reads: "The database version for WooCommerce. This should be the same as your WooCommerce version."

WooCommerce also keeps a log. Under WooCommerce, then Status, then Logs, open the newest file whose source is wc-updater. It says "Automatic database update triggered." or "Manual database update triggered.", then lists each step as it was scheduled.

When it is stuck

Open Scheduled Actions and search for woocommerce_run_update. The status of the rows tells you which case you have.

The actions stay at Pending

The queue is not being run. There are three things to check.

Is WP-Cron switched off?

wp config get DISABLE_WP_CRON

It prints 1 when the constant is set to true. An error saying the constant "is not defined" is the normal state: WP-Cron is on. WordPress's documentation pairs the constant with a job on the server that calls WP-Cron on a timer. With the constant set and no such job, visits to the storefront start nothing. The backup scheduling guide shows how to set that job up.

Can the site reach itself? Go to Tools, then Site Health. "Your site could not complete a loopback request" is the result to look for, and WordPress's documentation explains that loopback requests "are used to run scheduled events". From the command line:

wp cron test

A working site answers "Success: WP-Cron spawning is working as expected." For an error or a warning, the page on missed schedules goes through the causes and the fix for each.

Is the store quiet? WP-Cron runs only when a page is requested. WooCommerce's documentation says "scheduled tasks may be delayed if there is low traffic to your store".

Fix the cause afterwards. To get the update through now:

An action shows Failed

Read the Log column on the failed row. It holds one of these:

• "unexpected shutdown: PHP Fatal error" and the error. PHP stopped during the step, and the message says why: a memory limit or a time limit, for example.
• "action was in-progress for at least 300 seconds without completing and has been marked as failed." The step started and never reported back. The message goes on to say which logs to check.
• "action failed via", then how it was run and the error the step raised.

For a time limit, Maximum execution time exceeded explains where the limit is set and how to raise it for one long job.

So write down the step's name from the Arguments column and the message from the Log column. What the step does is a function of that name in includes/wc-update-functions.php inside the plugin, and running one by hand is work for a developer who has read it. The careful route is to restore the backup you took into a staging copy, run the update there from the command line, where the error prints in full, fix the cause, and then repeat it on the live store.

A large store, or a host with short time limits

WooCommerce's documentation offers the command line for this case: "advanced users may prefer to run these upgrades via the CLI, for example, on busy stores where timeouts could occur."

wp wc update

It runs every pending update step in turn, in the foreground, without the queue. It prints a line that begins "Found" with the number of steps and their names, and ends with a line such as "Success: 31 update functions completed. Database version is 11.2.0-1". It also removes the notice. Run it again and it answers "Success: No updates required. Database version is 11.2.0-1".

Use wp wc update when nothing is queued, which is when the notice still shows its button. It does not clear actions that are already in the queue. They stay at Pending and run the same steps a second time later. On a store with the automatic start the update is queued as soon as anything loads WordPress, so there run the queue with wp action-scheduler run, as shown above.

When the notice will not go away

WooCommerce's documentation says nothing about a notice that stays. The code that draws it makes two tests, and you can make the same two. Is the database version behind? Is a woocommerce_run_update_callback action waiting?

There is one trap. The notice shows "WooCommerce database update" whenever any woocommerce_run_update_callback action is waiting, including one that WooCommerce queued for another purpose. On a store with the automatic start switched off, it can say it is updating before you have pressed anything, and go back to "WooCommerce database update required" once that action has run. Selecting the button then is the right thing to do.

The tool that forces the update is under WooCommerce, then Status, then Tools. It is named "Update database", and its button has the same words. Its description reads: "Note: This tool will update your WooCommerce database to the latest version. Please ensure you make sufficient backups before proceeding." When used, it answers "Database upgrade routine has been scheduled to run in the background."

As that answer says, the tool queues the update. It does not run it. It queues the same actions as the button, so it helps when nothing is queued and does nothing for a queue that is stuck. Use it once. Each use while the database is behind adds the whole list to the queue again.

What not to do

• Do not restore the old database over the live store to clear the notice. The backup holds no order placed after it was made. Restore it and those orders are gone from the store, though the customers have paid. The failed update runbook sets out the choice between going back one version and restoring.
• Do not downgrade the plugin alone. WooCommerce's documentation says: "Reverting to an older version can cause data inconsistencies if the database schema has changed. Use this approach only on a staging environment, and restore a matching database backup before activating the older version."
• Do not cancel pending update actions. A canceled step does not run, and the last action still writes the new version number.
• Do not edit woocommerce_db_version by hand. WooCommerce decides which steps to run by comparing that value with its list. Raise it and the steps in between are never run.

If the message is about order tables

A message about order tables, order storage or synchronizing orders is a different job from the update on this page. It belongs to High-Performance Order Storage, which keeps orders in tables of their own where WooCommerce used to keep them in the tables WordPress uses for posts. It has been the default for new installations since WooCommerce 8.2.

The setting is under WooCommerce, then Settings, then Advanced, then Features. With compatibility mode on, WooCommerce copies orders between the two sets of tables through scheduled actions of its own, which appear on the same Scheduled Actions screen. WooCommerce's High-Performance Order Storage documentation covers switching, synchronizing and going back. Follow it for anything to do with those tables.

If you would rather hand this over, a one-time fix covers one issue on one site and starts with a free diagnosis. For the routine around every update, our WooCommerce maintenance service is the Store care plan: updates are tested on a staging copy first, and checkout and payment are tested after every update.