WooCommerce can migrate additional variation images from legacy extension metadata into the core gallery field. Large catalogs, custom importers, translated products, offloaded media, and theme overrides can expose gaps even when the migration reports completion.
Use this for stores that installed the WooCommerce Additional Variation Images extension or custom code around `_wc_additional_variation_images`, especially on multilingual, high-SKU, offloaded-media, or CDN-backed catalogs.
Quick answer
Back up the database, export a fixture of variation IDs and ordered image IDs, enable the core feature on staging, and let the documented batch migration run to completion. Compare the old and new metadata, edit a migrated product, view every variation on desktop and mobile, then repeat the migration to prove it is idempotent. Keep legacy metadata until rollback and custom integrations are verified.
What to check first
- Select fixtures covering zero, one, and many additional images, duplicate image IDs, deleted attachments, translated variations, imported products, and offloaded files.
- Export `_wc_additional_variation_images`, `_product_image_gallery`, attachment ownership, image order, URLs, and product modification dates before migration.
- Observe each 250-item batch, completion marker, Action Scheduler record, PHP log, timeout, retry, and memory peak on a production-sized clone.
- Open and save migrated variations in the product editor, then verify storefront swapping, zoom, lightbox, responsive sources, theme overrides, and mobile behavior.
- Repeat the migration, run existing importers, disable the standalone extension, purge image caches, and perform a database rollback rehearsal.
Diagnostic table
Use this table to keep the work practical. It connects the symptom to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Build the variation fixture export | Select fixtures covering zero, one, and many additional images, duplicate image IDs, deleted attachments, translated variations, imported products, and offloaded files. | The source and destination image-ID lists reconcile for every fixture. |
| Run migration on a full-size clone | Export `_wc_additional_variation_images`, `_product_image_gallery`, attachment ownership, image order, URLs, and product modification dates before migration. | Product edits and imports preserve the core gallery after migration. |
| Reconcile old and core metadata | Observe each 250-item batch, completion marker, Action Scheduler record, PHP log, timeout, retry, and memory peak on a production-sized clone. | Desktop, mobile, zoom, lightbox, srcset, CDN, and translated products show the intended images. |
| Update custom writers and templates | Open and save migrated variations in the product editor, then verify storefront swapping, zoom, lightbox, responsive sources, theme overrides, and mobile behavior. | A second migration and a rollback both produce predictable, documented results. |
Why this usually happens
- Legacy extensions and core use different metadata ownership rules.
- Missing attachments or duplicate IDs can break assumed gallery order.
- Importers may continue writing only the legacy key after migration.
- CDN and page caches can display stale image markup after correct database changes.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
variation_id: 4812
legacy_meta: [901, 904, 907]
core_gallery: [901, 904, 907]
batch_number: 12
completion_marker: true
second_run_delta: 0
storefront_order_matches: true
result: pass
Safe fix order
Do the work in a sequence that makes each result easy to prove. Stop if a step produces new evidence that changes the incident scope.
- Build the variation fixture export
- Run migration on a full-size clone
- Reconcile old and core metadata
- Update custom writers and templates
- Verify rollback and retire the extension
Decision rule
Pass when every valid legacy image appears once in the same order, broken references are reported, rerunning changes nothing, all active writers use the supported field, and the storefront stays correct after cache purge.
What to tell the client or owner
Give the owner the affected versions, exact workflow, observed result, business impact, evidence location, temporary control, named owner, and next review time. Remove credentials and personal data from shared screenshots and logs.
Production verification checklist
- The source and destination image-ID lists reconcile for every fixture.
- Product edits and imports preserve the core gallery after migration.
- Desktop, mobile, zoom, lightbox, srcset, CDN, and translated products show the intended images.
- A second migration and a rollback both produce predictable, documented results.
Mistakes to avoid
- Do not change several plugins, cache rules, or infrastructure settings before preserving a baseline.
- Do not treat one successful test as proof for retries, alternate clients, background work, or mixed-version fleets.
- Do not paste secrets, personal data, complete production payloads, or customer files into tickets or screenshots.
- Do not close the test until the final user-visible state and the server-side evidence agree.
Questions teams ask during testing
Can the old extension be removed immediately?
Wait until custom importers, feeds, themes, translated products, and rollback are verified. Core can deactivate the standalone feature, but your integrations still need testing.
Why keep legacy metadata temporarily?
The documented migration retains it, which preserves rollback evidence and helps compare old and new image lists while the transition is validated.
When HandL WP should help
Bring in HandL WP when a production checkout, form, email, media pipeline, code-quality gate, or paid lead workflow is at risk. We can preserve evidence, isolate the failing layer, make the smallest corrective change, and verify the result across WordPress, connected services, logs, and the user journey.
If this is active on a production site, migrate WooCommerce variation galleries safely.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Test the product gallery video experiment
When evaluating gallery video, run the WooCommerce 11.1 product gallery video beta accessibility test across keyboard, captions, reduced motion, mobile data, variants, analytics, performance, and image fallback.
Recover an automatically deactivated gallery extension
WooCommerce 11.1 moves additional variation images into core and can deactivate the older extension during its database update. Follow the WooCommerce 11.1 variation gallery migration recovery guide to reconcile update state, image IDs, REST fields, storefront behavior, caches, and rollback.
Helpful references