WooCommerce Update Broke My Store: How to Fix Database Updates, Outdated Templates, HPOS and Roll Back Safely

You updated WooCommerce and something went wrong. A banner says “WooCommerce database update required”. The cart or product page layout is broken. An extension throws errors, a shipping or invoice plugin no longer sees new orders, or the admin orders list looks empty. Sometimes the whole site shows a critical error.

A WooCommerce update is really three changes at once: new plugin code, a database migration that runs afterward, and a new set of template files that your theme may be overriding with older copies. Extensions built against the previous version then have to cope with all three. This guide works through each layer in order, and ends with how to roll back without losing orders. It is for store owners and the designers and developers who maintain their themes.

What is happening

Layer	What changes in an update	Typical symptom when it goes wrong
Plugin code	Functions, classes and hooks change or are deprecated	Fatal error from an extension calling something that moved
Database schema	New tables, columns or data migrations, run as background jobs after the update	“Database update required” notice; missing data; slow admin until it finishes
Templates	Files in woocommerce/templates/ gain new markup, hooks or fixes	Theme overrides in /woocommerce/ show old layouts, missing fields or broken buttons
Features	Defaults such as order storage or the block checkout change	Extensions that read orders from the old place see nothing

WooCommerce stores two version numbers in the database: woocommerce_version (the code that is installed) and woocommerce_db_version (the schema the data has been migrated to). When the second lags behind the first, migrations are pending. Those migrations run through Action Scheduler as actions with the hook woocommerce_run_update_callback in the group woocommerce-db-updates, so they depend on WP-Cron working.

A stuck “Briefly unavailable for scheduled maintenance” screen or an update that failed halfway is a different problem, covered in FG-19. A page builder layout broken by an update is covered in FG-07, and a general critical error in FG-02.

Before you start

• Backup first: take a fresh backup of files and database now, even though the site is broken. Orders placed since the update exist only in the current database.
• Staging: if your host offers one-click staging, clone the broken site and experiment there. Switch the gateway to test mode on the copy and make sure it cannot email customers or send live webhooks.
• Access: WordPress admin and SSH or SFTP. If the admin is down, WordPress recovery mode (the link in the error email) or SSH gets you in.
• Running commands on the server: SSH in and cd to the folder containing wp-config.php. WP-CLI is wp on most hosts and wp-cli on some.
• Running commands on your computer: curl and diff are built into macOS and Linux; on Windows use WSL.

Step 1: Record versions and read the error

wp plugin list --fields=name,status,version,update_version --format=table
wp option get woocommerce_version
wp option get woocommerce_db_version
wp theme list --status=active --fields=name,version

Where: server SSH, site folder. No placeholders. Flags: --fields chooses the columns, --format=table prints a readable table, and --status=active shows only the active theme (and its parent). Good output: the two WooCommerce version options match. Bad output: woocommerce_db_version lower than woocommerce_version, meaning migrations have not finished (Step 2). Save this output; you need it for rollback and for any support ticket.

Then open WooCommerce > Status > Logs and select the fatal-errors source. A fatal error names the file that crashed. If the path is inside an extension (/wp-content/plugins/PLUGIN_SLUG/), go to Step 4. If it is inside your theme’s /woocommerce/ folder, go to Step 3.

Step 2: Finish the database update

From the admin

The notice reads WooCommerce database update required with a button labeled Update WooCommerce Database. Click it once. The notice changes to say the update is running in the background. If it adds “Note: WP CRON has been disabled on your install which may prevent this update from completing”, the background jobs will not run on their own; use the CLI below or fix cron. WooCommerce > Status > Tools also has an Update database tool that starts the same routine.

From the command line

wp wc update

Where: server SSH, site folder. No placeholders or flags. This runs every pending migration in the foreground, so it does not depend on cron. Good output: Found N updates (...), a progress bar, then Success: N update functions completed. Database version is X.Y.Z, or Success: No updates required. Database version is X.Y.Z. Bad output: a PHP fatal error or a database error such as a missing privilege to alter tables. Copy the full message; a database user without ALTER or CREATE rights is a host-level fix. On a large store this can run for a long time, so use a terminal multiplexer such as screen or tmux if your SSH connection might drop.

If the update looks stuck

Open WooCommerce > Status > Scheduled Actions and search for woocommerce_run_update_callback. Failed actions show a log entry with the error. Pending actions whose date has passed mean the queue is not running. You can process just this group:

wp action-scheduler run --group=woocommerce-db-updates

Flags: --group limits the run to WooCommerce’s database update actions. Good output: a success line with the number of actions processed, after which wp option get woocommerce_db_version matches the code version. Bad output: repeated failures with the same error, which you should send to your developer or host. General cron and Action Scheduler stalls are covered in FG-33.

Step 3: Fix outdated template overrides

Themes customize WooCommerce by copying template files into a woocommerce folder inside the theme, for example wp-content/themes/THEME/woocommerce/cart/cart.php. WooCommerce then loads the theme’s copy instead of its own. Each template carries an @version line in its header comment. When WooCommerce changes a template, the theme’s old copy keeps running, and anything new (a hook, a field, a security fix, a renamed CSS class) is missing.

Find them

Go to WooCommerce > Status (System status tab) and scroll to Templates. The Overrides row lists every file your theme overrides. Outdated ones are marked “Version X is out of date. The core version is Y”, and an Outdated templates row links to Learn how to update. Since WooCommerce 11.0 the same check also appears in Tools > Site Health as “Your theme contains outdated WooCommerce template overrides”.

Prove the override is the cause

On staging, rename the theme’s override folder so WooCommerce falls back to its own templates:

mv wp-content/themes/THEME/woocommerce wp-content/themes/THEME/woocommerce-disabled

Where: server SSH, site folder. Placeholder: THEME is the folder name of the theme listed in the Templates section (often a child theme). Good result: the broken page works again, perhaps with plainer styling, which proves an override caused it. Rename it back with the same command reversed. Renaming a single file instead (for example cart/cart.php) narrows it down to one template.

Update the override properly

diff -u wp-content/plugins/woocommerce/templates/cart/cart.php wp-content/themes/THEME/woocommerce/cart/cart.php

Placeholders: THEME as above; replace cart/cart.php with the path shown in the Templates list. Flags: -u prints a unified diff, with lines starting - present only in the core template and + only in your override. How to read it: the + lines are your customizations; the - lines include what WooCommerce added since the copy was made.

• Override in your own child theme: copy the current core template over the override, reapply only your customizations from the diff, and update the @version line to match core. Test the page.
• Override in a commercial parent theme: do not edit it. Update the theme; theme authors ship updated overrides. If no update exists yet, ask the theme author, or move the essential customizations into a child theme override you control.
• Override you no longer need: delete it. Fewer overrides mean fewer breakages on every future update. Many layout changes can be done with hooks or CSS instead.

Block themes work differently: store pages are block templates edited in the Site Editor. If a customized block template looks wrong after an update, compare it with the default in the Site Editor and reset the customization if needed.

Step 4: Check extension compatibility

Extensions declare which WooCommerce versions they support with WC requires at least and WC tested up to headers. A fatal error naming an extension right after a WooCommerce update almost always means it needs its own update.

grep -H "WC tested up to" wp-content/plugins/*/*.php

Where: server SSH, site folder. No placeholders. Flags: -H prints the file name next to each match, so you know which plugin it belongs to. Good output: each WooCommerce extension lists a version at or above the one you installed. Bad output: extensions tested only up to much older versions. Those are your suspects; check for updates, and note that extensions bought from WooCommerce.com only update when the store is connected to a WooCommerce.com account (Site Health flags this).

WooCommerce also tracks feature compatibility. WooCommerce > Settings > Advanced > Features lists features such as order storage, and flags active plugins that have declared themselves incompatible with them. If you cannot update a crashing extension and the store must trade, deactivate it with wp plugin deactivate PLUGIN_SLUG (the folder name from the error path) and replace its function temporarily.

Step 5: Check HPOS order storage and sync

High-Performance Order Storage (HPOS) keeps orders in dedicated tables (wp_wc_orders, wp_wc_orders_meta, wp_wc_order_addresses and wp_wc_order_operational_data) instead of the posts tables. It has been the default for new stores since WooCommerce 8.2, and older stores can switch to it. The setting lives at WooCommerce > Settings > Advanced > Features under order data storage, with the choices High-performance order storage (recommended) and WordPress posts storage (legacy), plus a checkbox labeled Enable compatibility mode (Synchronize orders between High-performance order storage and WordPress posts storage).

The classic symptom: an extension that reads wp_posts directly, instead of using WooCommerce’s order functions, suddenly sees no new orders. Reports go blank, fulfillment exports miss orders, or a custom query returns nothing.

wp wc hpos status
wp wc hpos count_unmigrated
wp wc hpos compatibility-info

Where: server SSH, site folder. No placeholders. Good output: status prints lines such as HPOS enabled?: yes, Compatibility mode enabled?: yes and Unsynced orders: 0; compatibility-info lists which active plugins are compatible, incompatible or undeclared. Bad output: a large number of unsynced orders, or incompatible plugins while compatibility mode is off.

If an incompatible extension must keep working, turn on compatibility mode so both stores stay in step, then let the sync finish:

wp wc hpos compatibility-mode enable
wp wc hpos sync --batch-size=BATCH_SIZE
wp wc hpos verify_data

Placeholder: BATCH_SIZE is how many orders to copy per batch; a few hundred is gentle on a shared server. What each does: the first turns on two-way synchronization, the second copies any orders not yet in the other storage, and the third compares the two and reports differences. Good output: sync finishing with no errors and verification reporting no differences. Bad output: differences for specific orders; inspect one with wp wc hpos diff ORDER_ID, where ORDER_ID is an order number from the report. Switching the authoritative storage back to posts is possible when the data is in sync, but treat it as a temporary measure while the extension is fixed, and do it on staging first.

Step 6: Roll back WooCommerce, with care

Rolling back the code is one command. Rolling back the data is the hard part.

wp plugin install woocommerce --version=VERSION --force

Where: server SSH, site folder. Placeholder: VERSION is the previous version you recorded in Step 1, for example the number shown before the update. Flags: --version downloads that exact release from WordPress.org and --force overwrites the installed copy. Good output: Plugin installed successfully and Success: Installed 1 of 1 plugins. Bad output: a download error, which usually means a typo in the version.

The database caveats:

• Migrations do not reverse. If the new version already migrated the database, the old code now runs against a newer schema. Across a minor release that often works; across major releases it may not. woocommerce_db_version will stay at the newer number.
• Restoring a database backup loses new orders. Every order, customer and stock change since the backup disappears. Export those orders first (or note them from the gateway dashboard) and re-enter them.
• Order storage changes carry over. If the update moved you to HPOS, an older version that does not know the current state can show missing orders. Check Step 5 after any rollback.

The safest rollback is a full restore of files and database to the moment before the update, done quickly, followed by re-entering the few orders taken since. A code-only rollback is a short-term bridge while you fix the real cause. Stop auto-updates repeating the problem with wp plugin auto-updates disable woocommerce until you have tested on staging.

Advanced: See exactly what changed between two versions

Before you update overrides or blame an extension, look at what really changed. Download both releases and compare their templates:

mkdir wc-compare && cd wc-compare
curl -sO https://downloads.wordpress.org/plugin/woocommerce.OLD_VERSION.zip
curl -sO https://downloads.wordpress.org/plugin/woocommerce.NEW_VERSION.zip
unzip -q woocommerce.OLD_VERSION.zip -d old && unzip -q woocommerce.NEW_VERSION.zip -d new
diff -rq old/woocommerce/templates new/woocommerce/templates

Where: your computer, in an empty working folder. Placeholders: OLD_VERSION and NEW_VERSION are the version numbers from Step 1. Flags: -sO downloads silently and keeps the file name, unzip -q -d extracts quietly into the named folder, and diff -rq compares recursively and only names the files that differ. Good output: a short list of changed templates; check whether any are in your theme’s override list, then run diff -u on those files to read the change. Bad output: unzip errors mean the download failed, usually a mistyped version.

For code changes, read the release notes in the changelog.txt file at the root of the WooCommerce GitHub repository, or the plugin’s changelog on WordPress.org. Search them for words from your error (a function name, a hook, “deprecated”, “template”, “HPOS”). Each line links to the pull request that made the change, which often explains the new way to do the old thing.

A sound update routine for any store with revenue: clone to staging, update the theme and extensions, update WooCommerce, run wp wc update, check the Templates section and Site Health, place test orders with every gateway and shipping method, check emails and one extension report, then repeat on live in a quiet hour with a fresh backup.

When to contact your host

Contact your host when the database update fails with permission errors, when WP-CLI or cron is unavailable, when you need a restore from the host’s backups to a precise time, or when the update leaves the server under heavy load. Send:

• The old and new WooCommerce versions and the UTC time of the update.
• The output of the version commands from Step 1.
• Lines from fatal-errors or the failed Action Scheduler entries.
• Whether you need a database restore, and the exact time it should be restored to.

The diagnostic tools page can help you capture the error state first. If the store is down and taking no orders, start at the Emergency Room.