WooCommerce 11.1 moves Additional Variation Images data into core and schedules an Action Scheduler job that handles up to 250 variations per run until none remain. Large catalogs can accumulate queue age, retries, failed actions, worker contention, and new catalog edits while the migration is still in progress.
Use this for large or multilingual catalogs, ERP and PIM integrations, busy Action Scheduler queues, slow hosting, custom gallery code, and stores that need a clear point for resuming catalog changes.
Quick answer
Count affected variations before the update and calculate an expected minimum batch count as ceiling(total divided by 250). Record action name, scheduled time, started time, completed time, attempts, processed count, failed count, remaining legacy rows, remaining empty core galleries, queue age, worker concurrency, PHP memory, and database load. Pause bulk gallery edits during the controlled window. Alert when the oldest action or failure ratio crosses the written service level, then inspect the first failed variation rather than repeatedly launching more workers.
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| 249 variations | One batch | All processed |
| 250 variations | One batch boundary | No remainder |
| 251 variations | Two batches | One in second |
| Failed item | Unreadable attachment | Recorded and recoverable |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence | Verification |
|---|
| Count affected variations | Record WooCommerce version, catalog size, affected variation count, Action Scheduler store, runner type, interval, concurrency, batch size, PHP limits, database load, and integration write schedule. | Observed batch count and processed totals reconcile with the original affected variation inventory. |
| Set queue-age and failure thresholds | Export variation IDs with legacy metadata, core gallery metadata, featured image, language relationship, parent product, last edit time, and expected migration state before updating. | No failed or stale migration action remains without an owner and reason. |
| Pause conflicting catalog writes | Track every scheduled action, start and finish time, attempts, processed and failed IDs, remaining count, oldest queue age, memory peak, query time, lock waits, and worker exit status. | Core gallery metadata, REST output, translations, and storefront image order agree. |
| Observe batches and first failures | Test interruption after one batch, retry of the same batch, new variation created during migration, gallery edited during migration, failed attachment, deleted attachment, and translated product. | Queue age, database load, and worker capacity return to their normal operating range. |
What to check first
- Record WooCommerce version, catalog size, affected variation count, Action Scheduler store, runner type, interval, concurrency, batch size, PHP limits, database load, and integration write schedule.
- Export variation IDs with legacy metadata, core gallery metadata, featured image, language relationship, parent product, last edit time, and expected migration state before updating.
- Track every scheduled action, start and finish time, attempts, processed and failed IDs, remaining count, oldest queue age, memory peak, query time, lock waits, and worker exit status.
- Test interruption after one batch, retry of the same batch, new variation created during migration, gallery edited during migration, failed attachment, deleted attachment, and translated product.
- Compare expected minimum batches with observed runs and do not declare completion until legacy candidates, core records, storefront order, API output, and scheduled actions reconcile.
Field notes
- Write the pass condition before changing anything. A repeatable synthetic fixture makes the before and after comparison useful.
- Keep exact versions and UTC timestamps because scheduled jobs, caches, retries, and background processing can change the evidence.
- Check the public experience and the stored server-side result. Admin previews and isolated API calls do not prove the whole workflow.
- Repeat the test after the relevant cache, queue, scheduled action, webhook, and observation window has finished.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
wp action-scheduler list --status=pending --format=table
wp action-scheduler list --status=failed --format=table
wp db query "SELECT COUNT(*) FROM wp_postmeta WHERE meta_key='_wc_additional_variation_images';"
# Record counts before and after each observed batch.
Why this usually happens
- A busy Action Scheduler queue delays migration behind unrelated subscriptions, webhooks, or imports.
- A worker times out after some writes and repeats an idempotent batch later.
- Catalog automation continues writing the legacy key while core migration is running.
- Teams count completed actions but never reconcile variations that remain unmigrated.
Decision rule
Resume normal catalog edits only when no migration action is pending or failed, every affected variation has the intended core gallery, storefront and API order match, and monitoring shows the queue has returned to normal age.
Production verification checklist
- Observed batch count and processed totals reconcile with the original affected variation inventory.
- No failed or stale migration action remains without an owner and reason.
- Core gallery metadata, REST output, translations, and storefront image order agree.
- Queue age, database load, and worker capacity return to their normal operating range.
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Count affected variations
- Set queue-age and failure thresholds
- Pause conflicting catalog writes
- Observe batches and first failures
- Reconcile data and storefront output
Mistakes to avoid
- Changing production before recording exact versions, UTC time, the affected fixture, current behavior, and a tested rollback point.
- Accepting one successful admin screen while the public page, stored record, API response, accessibility tree, queue, email, or downstream system remains unchecked.
- Testing only as an administrator instead of the role, browser, device, locale, network state, and failure path that a real customer reaches.
- Leaving broad credentials, debug logs, temporary filters, synthetic records, or recovery code active after verification.
Questions teams ask during testing
Should I test this on production?
Use production for read-only evidence first. Reproduce the change on staging with a current data shape, theme, extensions, cache, and browser mix. If a production canary is necessary, make it reversible, identifiable, monitored, and unable to charge a customer or expose personal data.
How do I rule out a cache artifact?
Record the origin response, purge only affected paths, and repeat in private and normal sessions. Compare stored data and server logs with the visible page. A cache hit is useful evidence only when you know which version it contains.
What belongs in the evidence packet?
Keep UTC time, exact versions, fixture ID, role, browser, expected result, actual result, relevant response or log lines, change made, rollback point, owner, and final verification. Redact passwords, tokens, personal data, and private URLs.
When is the test complete?
Close it when the main path and important failure branches pass, records reconcile across systems, accessibility and mobile checks are complete, temporary changes are removed, and monitoring covers the next update or business cycle.
What to tell the client or owner
Give the owner a short packet with the affected workflow, exact versions, UTC test time, fixture ID, expected result, actual result, key evidence, change made, rollback point, unresolved risk, owner, and next review date. Remove credentials and personal data before sharing it.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, have HandL WP monitor a WooCommerce migration.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references