Troubleshooting · Troubleshooting
How to Fix "WooCommerce Database Update Required"
Short answer
The “WooCommerce Database Update Required” notice means the plugin files were updated but the database changes for the new version have not run yet. Back up the database first, then click Update WooCommerce Database once and watch the progress in Scheduled Actions. Do not run it twice, and do not skip the backup.
Key takeaways
- The notice means the plugin files are newer than the database, not that data is lost.
- Back up the database and files before clicking Update WooCommerce Database.
- Click the update button once, then watch progress in Scheduled Actions.
- The database version on the Status screen should match the plugin version when done.
- A returning notice means the background jobs stalled, so check Scheduled Actions first.
What does “WooCommerce Database Update Required” mean?
It means the plugin files are on a newer version than the database, and WooCommerce has database work waiting to run.
A WooCommerce update has two parts: new plugin files, and changes to the saved store data so the new files can work with it. The notice appears when the first part is done and the second part is still waiting.
WooCommerce's update guide says some updates require a database update after the plugin files update, and a database update notice appears in the admin dashboard when this is required (How to update WooCommerce). The notice does not by itself mean products or orders are damaged.
Is the notice urgent, and can the store keep selling?
It is a maintenance job, not an emergency, but finish it before you change anything else in the store.
Shoppers can usually still browse and buy while the notice is showing, because the old data still works. The risk is running more updates, changing settings, or editing products while the database is half-migrated, which can leave orders or settings in an odd state.
WooCommerce's update guide says the database update notice should be run only after you have a current backup, and to complete the database update before you continue testing the store (How to update WooCommerce). Set the store to Coming soon mode during the update window if you can, so no customer checks out mid-migration.
How do you back up before running the update?
Take a full backup of the database and the site files, and confirm the backup is complete before you touch the update button.
WooCommerce's update guide says a store keeps data in two places: the wp-content folder, which holds themes, extensions and uploads, and the database, which holds products, orders, posts, pages and settings (How to update WooCommerce). Back up both, not just one.
- Back up the database with your host tool or a backup plugin.
- Download the wp-content folder over SFTP.
- Confirm the backup file exists and has a recent time stamp.
- If possible, test the update on a staging copy first.
WooCommerce's update guide says to test updates on staging before customers are affected, and never to test updates directly on the production site (How to update WooCommerce). The safe update order is covered in How to Update WooCommerce Safely.
How do you run the WooCommerce database update?
Click Update WooCommerce Database once, then watch the progress instead of clicking again.
WooCommerce's update guide says the button updates the database to match the new WooCommerce version, and that a backup must be in place before clicking it (How to update WooCommerce). The update runs in the background, so the page may look unchanged for a while.
After you click, a WooCommerce database update notice appears. WooCommerce's update guide says to click View progress to open Scheduled Actions and monitor the pending database update actions (How to update WooCommerce). When the update finishes, a dismissible WooCommerce database update complete message confirms it is done.
| Step | Where | What to check |
|---|---|---|
| Back up | Host tool or backup plugin | Database and wp-content both saved |
| Run the update | Admin notice button | Click once only |
| Watch progress | View progress, Scheduled Actions | Pending actions falling to zero |
| Confirm completion | Admin notice | “Database update complete” message |
| Test the store | Storefront, cart, checkout | Test order, shipping, tax, email |
WooCommerce also has the same update as a tool. Its system tools guide says the Update the WooCommerce database tool updates the database to the latest version, and to always back up the database before running it (WooCommerce System Tools).
How do you check the update finished?
Compare the two version numbers on the Status screen, and confirm the complete message appeared.
Open WooCommerce > Status and read the WooCommerce Version and the WooCommerce Database Version. WooCommerce's mobile app troubleshooting guide says the database version value should match the installed WooCommerce version value on the same page (Troubleshooting errors loading data). If the two numbers match, the update finished.
The report itself is explained in How Do You Read the WooCommerce Status Report?. If the numbers still differ, open WooCommerce > Status > Scheduled Actions and look for pending database update actions before you try again.
WooCommerce 11.3.1 was released on 19 November 2026, so confirm the store is on a current release while you are on the Status screen (WooCommerce).
What if the notice comes back after the update?
The background jobs did not finish, so find why they stalled instead of clicking the button again and again.
First, open WooCommerce > Status > Scheduled Actions and check whether database update actions are still pending or marked as failed. WooCommerce's update guide says the View progress link opens Scheduled Actions for exactly this check (How to update WooCommerce).
A common cause is WP-Cron not running, because the background jobs depend on it. The steps for past-due background jobs are covered in How to Fix Past-Due Actions in the WooCommerce Action Scheduler.
Another cause is a missing or broken database table. WooCommerce's system tools guide says the Check for missing WooCommerce tables tool confirms all required tables are present, and to back up the database before running repairs (WooCommerce System Tools). The repair steps are covered in How to Fix Corrupted Database Tables in WordPress.
If the store shows a database connection error instead of the notice, that is a different fault: the database itself is unreachable, not waiting for a migration.
What if the update fails halfway?
Stop, read the error, and restore from the backup if the store is broken, rather than running the update again on damaged data.
A failed update can leave some tables migrated and others not. Open WooCommerce > Status > Logs and read the fatal-errors log for the first error at the time the update ran. A database error there usually names the missing privilege or the table that failed.
WooCommerce's update guide says that if something does not work as expected, keep the site out of checkout, restore from the backup if needed, and troubleshoot on staging before trying again on production (How to update WooCommerce).
WooCommerce's server recommendations ask for MySQL 8.0 or greater, or MariaDB 10.6 or greater, and a WordPress memory limit of 256 MB or more (WooCommerce Server Recommendations). A store below those numbers can fail a migration that a better server would finish.
The PHP project lists security fixes for PHP 8.3 until 31 December 2027 and for PHP 8.4 until 31 December 2028 (Supported Versions).
WordPress.org's requirements page asks for PHP 8.3 or greater and MariaDB 10.11 or greater or MySQL 8.4 or greater (Requirements).
How do you test the store after the update?
Run the same checks WooCommerce lists after any update: storefront, cart, test order, shipping, tax, payment and email.
WooCommerce's update guide lists the post-update checks: open the storefront and several product pages, add a product to the cart, place a test order, and check shipping, tax, payment and email behavior (How to update WooCommerce). Run each one and note the result before you turn off Coming soon mode.
- Product pages load with the right prices.
- The cart keeps its items to checkout.
- A test order completes and appears in WooCommerce > Orders.
- The order email arrives.
- No new update notice appears in the admin.
WooCommerce's performance guide also recommends regular database clean-ups, removing spam comments, post revisions and expired transients, so a tidy database is part of staying current (How to optimize performance for WooCommerce stores).
If the store gets stuck in maintenance mode during the update, the steps in How to Fix a Site Stuck in Maintenance Mode in WordPress clear it.
If another update is already running, see Fix 'Another Update Is Currently in Progress' in WordPress.
What mistakes should you avoid?
Do not run the update without a backup, do not click the button twice, and do not run other updates at the same time.
- Clicking twice can start two migrations at once and leave tables half-changed.
- Updating extensions, the theme and WooCommerce in one go hides which change caused a fault.
- Editing products or settings during the migration can clash with the data being changed.
- Skipping the staging test means the first run happens on the live store.
WooCommerce's update guide says to avoid running multiple major store updates at the same time unless that exact update set was already tested on staging (How to update WooCommerce).
Frequently asked questions
Does the database update notice mean my products or orders are damaged?
No, not by itself. It means database work from the new version has not run yet, not that data is lost. Back up the database, click Update WooCommerce Database once, and check that the database version matches the plugin version on the Status screen when it finishes.
How long does the WooCommerce database update take?
Click it once and wait. The update runs as background jobs, so the page may look unchanged for a while. Click View progress to open Scheduled Actions and watch the pending actions fall to zero, then look for the database update complete message.
Can customers still buy while the database update notice is showing?
Yes, in most cases, but it is safer to finish the update first. The store is half-migrated while the notice is showing, so further changes can clash with the migration. Set the store to Coming soon mode during the update window if you can.
Why does the notice come back after I ran the update?
The background jobs did not finish. Open WooCommerce > Status > Scheduled Actions and look for pending or failed database update actions. WP-Cron not running is a common cause, and a missing table is another. Fix that cause before you run the update again.
How do I know the database update finished?
Open WooCommerce > Status and compare the WooCommerce Version with the WooCommerce Database Version. If the two numbers match, the update finished. Also look for the dismissible database update complete message in the admin.
What should I do if the database update fails halfway?
Restore from the backup you took before the update, then troubleshoot the error on a staging copy. WooCommerce's update guide says to keep the site out of checkout and restore from backup if needed, rather than retrying on production with damaged data.
Sources
- How to update WooCommerce WooCommerce
- WooCommerce System Tools WooCommerce
- Troubleshooting errors loading data WooCommerce
- WooCommerce Server Recommendations WooCommerce
- Requirements WordPress.org
- WooCommerce WordPress.org
- Supported Versions PHP
- How to optimize performance for WooCommerce stores WooCommerce Developer Docs
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
