Why do copied WooCommerce image files fail to appear in the migrated product gallery?

Separate the Three Layers

Start with one migrated product and record its product identity, such as the SKU or another identifier preserved from the original store. Then inspect the copied file itself, the corresponding Media Library attachment, and the product edit screen. A file can exist at a reachable path while lacking a Media Library attachment, and an attachment can exist without being assigned to that product.

Do not treat a successful file copy as proof that the gallery should display the image. The gallery depends on the product record containing the image reference or assignment. Preserve the original product identity while testing so the importer updates the intended product rather than creating an unrelated record.

When an Images cell contains multiple image references, the native schema uses a comma-separated list: enclose the complete CSV cell in double quotes so those commas stay inside one field. The first reference is the featured image. For an update to existing products, select Update existing products and confirm the ID or SKU mapping. Leave unchanged media out of copy-only updates.

1. Open the migrated product and note whether the main image and gallery area are empty, partially populated, or populated with the wrong images.
2. In Media Library, find the suspected attachment and inspect its file reference, attachment identity, and whether its preview loads.
3. Compare the attachment’s file with the copied filesystem object. Confirm that the filename and location you are checking are the same values used by the migration data.
4. Export a sample product from the destination store and inspect the exact image-related column header and row format. Use that built-in exporter output as the pattern for the importer.

Use the Importer’s Image Field

For a controlled test, create a non-destructive copy of one product row and populate the importer’s image field using the format shown in the exported sample. The image URLs must be reachable by the importer. Existing images may be referenced, so a copied file does not necessarily need to be uploaded again if the importer can reach the existing image reference.

Use the built-in WooCommerce Product CSV Importer and its own mapping. Do not substitute an extension’s CSV instructions. Review the mapping before import, and use the importer’s update-matching option when the row is intended to update the preserved product rather than create a new one.

1. Prepare one row with the preserved product identifier and the exact image-column format from the destination export.
2. Run the smallest available test import and inspect its importer messages or results for image-related failures.
3. Reopen the product, then inspect both the featured image and gallery assignments.

Branch on the Evidence

If the image appears in Media Library but not on the product, do not recopy the file first. Correct the product-row reference or mapping. If the importer cannot reach the image, attachment inspection cannot compensate for that access failure.

Illustrative exercise

Illustrative exercise: define Asset A as a file named blue-mug-front.jpg, intended to be the product’s main image. Define Asset B as blue-mug-handle.jpg, intended to be a gallery image. Put both references in one test row using the exact image-column syntax shown by the destination’s exported sample, with Asset A first.

Pass means the preserved product is updated, Asset A appears as the featured image, Asset B appears in the gallery, and both corresponding attachments preview in Media Library. Fail means either file is reachable but absent from the product assignments, the order makes Asset B featured, or the row creates a separate product. Each failure identifies a different layer to correct.

Acceptance Condition

Expand only after the test row passes all four checks: the intended product identity was matched, both image references were reachable, the attachments are present and previewable, and the product displays the first image as featured with the second in the gallery. Keep the original export and test row so a failed larger import can be compared without guessing which layer changed.

Scope of the documentation

The official references below support tool behavior and feature boundaries. The test fixture, branching decisions and acceptance criteria are Itemlume editorial recommendations; citation does not imply endorsement. Illustrative sizes, names and timings are not your production specifications.