WooCommerce 11.1 migrates Additional Variation Images data into _product_image_gallery through idempotent Action Scheduler batches of up to 250 variations and preserves legacy metadata. Repeated IDs, stale legacy values, shared attachments, and custom writes can look like duplicates but require different actions.
Use this for large variable-product catalogs, stores retiring Additional Variation Images, offloaded media, multilingual products, imported catalogs, custom gallery code, and shared product photography.
Quick answer
Let the official migration queue finish before cleanup. Export each variation ID, parent product, featured image, legacy gallery value, canonical gallery value, gallery order, attachment existence, file URL, reference count, language relationship, and last writer. Classify exact duplicate IDs within one gallery, legacy-only rows, canonical-only rows, conflicting ordered sets, missing attachments, and files referenced elsewhere. Normalize only canonical gallery values after staging verification. Preserve legacy metadata for compatibility unless a tested retirement plan says otherwise, and never delete an attachment until every product, variation, post, translation, revision, and external index reference has been checked.
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 |
|---|
| Exact repeat | ID appears twice in canonical list | Deduplicate order safely |
| Legacy only | Canonical empty | Confirm migration queue |
| Shared attachment | Referenced by three products | Do not delete file |
| Conflicting order | Legacy differs from core | Choose tested source of truth |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence | Verification |
|---|
| Wait for migration completion | Record WooCommerce version, database update state, Additional Variation Images status, Action Scheduler queue, batch completion, catalog size, offload plugin, languages, and custom gallery writers. | Action Scheduler migration is complete with no failed related jobs. |
| Export both metadata sources | Export legacy and canonical meta beside the variation featured image, ordered attachment IDs, REST gallery_image_ids, rendered storefront gallery, and attachment reference counts. | Canonical gallery order renders correctly for every tested variation. |
| Classify duplicates and references | Separate repeated IDs in one list, identical legacy and canonical lists, different order, missing files, shared media, translated relationships, and active custom writes. | REST, import, export, mobile, cache, and rollback fixtures pass. |
| Repair canonical data in batches | Test simple selection, variation switching, no-gallery fallback, gallery clearing, REST read and write, import and export, mobile zoom, thumbnails, rollback, and cache cycles. | No shared or translated attachment was deleted during cleanup. |
What to check first
- Record WooCommerce version, database update state, Additional Variation Images status, Action Scheduler queue, batch completion, catalog size, offload plugin, languages, and custom gallery writers.
- Export legacy and canonical meta beside the variation featured image, ordered attachment IDs, REST gallery_image_ids, rendered storefront gallery, and attachment reference counts.
- Separate repeated IDs in one list, identical legacy and canonical lists, different order, missing files, shared media, translated relationships, and active custom writes.
- Test simple selection, variation switching, no-gallery fallback, gallery clearing, REST read and write, import and export, mobile zoom, thumbnails, rollback, and cache cycles.
- Repair metadata in small reversible batches, re-run reference counts, purge only affected caches, and monitor Action Scheduler plus custom writers for recurrence.
Field notes
- Write the pass condition before changing anything and keep one repeatable synthetic fixture for the full test window.
- Record exact versions and UTC timestamps because deployments, caches, retries, scheduled actions, and background jobs can change the evidence.
- Test the public path and the stored server-side result, not only an admin preview, isolated command, or API response.
- Repeat verification after the relevant cache, queue, cron, webhook, and observation window has completed.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
variation_id,legacy_ids,canonical_ids,featured_id,reference_count,class,action
8101,"41,42","41,42,42",40,3,repeat-id,dedupe-meta
8102,"51,52","",50,2,migration-pending,inspect-queue
Why this usually happens
- A custom writer appends IDs without checking the existing ordered list.
- Migration has not completed or a failed batch is waiting in Action Scheduler.
- Legacy metadata is intentionally preserved and mistaken for a second live gallery.
- An attachment is shared across variations, languages, or parent products.
Decision rule
Clean only after migration completion and reference analysis. Remove duplicate metadata values when verified, but delete physical media only when no approved reference remains.
Production verification checklist
- Action Scheduler migration is complete with no failed related jobs.
- Canonical gallery order renders correctly for every tested variation.
- REST, import, export, mobile, cache, and rollback fixtures pass.
- No shared or translated attachment was deleted during cleanup.
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.
- Wait for migration completion
- Export both metadata sources
- Classify duplicates and references
- Repair canonical data in batches
- Retest storefront and REST
Mistakes to avoid
- Changing production before recording exact versions, UTC timestamps, a stable fixture, the expected result, and a tested rollback point.
- Treating one successful screen as proof while stored records, logs, queues, caches, emails, APIs, and downstream systems remain unchecked.
- Testing only as an administrator instead of using the role, device, locale, cache state, and failure branch that real users reach.
- Leaving temporary exclusions, debug output, helper accounts, broad permissions, or one-off repair code active after verification.
Questions teams ask during testing
Can I run this directly in production?
Begin with read-only evidence and use staging for package, code, database, form, or permission changes. If a production canary is necessary, make it identifiable, reversible, monitored, and unable to expose personal data or charge a customer.
How do I avoid a false positive?
Repeat the same fixture with the same versions, role, URL, locale, cache state, and downstream integrations. Compare browser, stored, and log evidence instead of relying on one screen.
What should the evidence packet contain?
Keep UTC time, exact versions, synthetic record ID, expected result, actual result, relevant log lines, change made, rollback point, owner, and final verification. Redact secrets and personal data.
When is the test complete?
Close the work when the primary path passes, failure branches are understood, stored and downstream records reconcile, temporary changes are removed, and monitoring covers the next update.
What to tell the client or owner
Give the owner a concise packet with the affected workflow, exact versions, UTC test time, fixture ID, expected result, actual result, key logs, change made, rollback point, final result, unresolved risks, 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 audit a variation gallery migration.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references