Image Issues

Image Issues

Restore each required image to the correct migrated record without hiding the root cause or introducing inconsistent manual fixes. Use this page when a Product, Category, CMS Page, Blog Post, or other supported record exists in the target store but an expected image is missing, broken, incomplete, duplicated, or attached to the wrong record.

An image problem can occur before the file is read, while it is transferred or processed, when it is associated with a target record, or only when the target storefront renders it. Identify the failing layer before starting another migration activity or editing a large number of target records.

Do not broadly disable security or change server settings

A firewall, CDN, hotlink rule, authentication layer, or hosting restriction can block image access. Ask the responsible platform, hosting, or security owner to verify the specific blocked request. Do not broadly disable protections or enable server features from generic advice.

Identify the observable problem

Observable problem	What it usually means
The migrated record exists but no image is present	The source image may not have been available, selected, read, processed, or associated with the record.
The target record contains a broken image or placeholder	The stored image URL, file path, target media record, storage location, or generated asset may be invalid or unavailable.
Only some images are missing	The affected files may use different paths, hosts, permissions, formats, sizes, or source-record associations.
The primary image appears but gallery images do not	The source image set, image-role relationship, target gallery model, or processing result may be incomplete.
The wrong image is attached to a record	A source-to-target identifier, relationship, mapping, duplicate-record, or association issue may exist.
Images appear in the target admin area but not on the storefront	A target theme, publication state, sales channel, cache, index, template, or presentation rule may be hiding them.
Thumbnails appear but full-size images fail, or the reverse	The target platform may have failed to generate or serve one image derivative, size, or storage path.
Images load intermittently	The source host, CDN, signed URL, rate limit, firewall, network, or target storage service may be unstable or time-limited.
The image is present but cropped, compressed, rotated, or resized unexpectedly	The target platform or theme may be applying its own image processing and presentation rules.

Collect a representative sample

Choose a small sample that exposes the pattern before changing configuration or target data. Include, where applicable:

• one record whose image migrated correctly;
• one record with a completely missing image;
• one record with a broken target image;
• one record with multiple images or image roles;
• one unusually large image or uncommon file format;
• one image stored on a different domain, CDN, folder, or source path;
• one record where the target admin and storefront show different results.

For each sample, record the source record identifier, source image location, target record identifier, expected image role, actual result, and the migration activity reviewed. Do not include credentials, private access tokens, signed query values, customer personal data, or unrelated files in the evidence.

Diagnose the failing layer

1. Confirm the migration activity and target environment

   Verify that the image check belongs to the intended purchased service, migration path, source-data window, activity, and target store. Stop if you are reviewing a staging store, copied store, earlier result, or unrelated activity.

2. Confirm that the underlying record migrated

   Search the target by a stable identifier such as source ID, SKU, target ID, slug, or another approved key. Use Missing Data when the Product, Category, CMS Page, Blog Post, or other parent record is absent.

3. Match the complete source image set

   Compare the source record’s primary image, gallery images, thumbnails, attachments, and applicable content images with the expected target representation. Confirm that the source files existed and belonged to the correct record when the migration activity ran.

4. Check source image accessibility

   Confirm that each affected image can be accessed through the supported source setup. Identify expired or signed URLs, authentication requirements, blocked external requests, hotlink protection, CDN restrictions, missing local files, custom paths, or incomplete source exports.

5. Review processing evidence

   Check the affected data type’s Success, Failed, and Skipped results and the migration log where available. Determine whether the parent record succeeded while the image failed, or whether the image issue reflects a broader record-processing problem.

6. Check target file acceptance and storage

   Confirm whether the target platform accepts the affected format, file size, dimensions, filename, and storage behavior. Compare a working and failing sample rather than assuming one universal platform limit.

7. Verify image-to-record association

   Confirm that the target image belongs to the correct Product, variant, Category, CMS Page, Blog Post, language, site, or channel. Review duplicate records, identifier changes, Advanced Data Mapping, Advanced Database Mapping, or approved Customization when the association is wrong.

8. Separate stored-media issues from storefront presentation

   Check the target admin record, direct media result where appropriate, storefront, theme, channel, publication state, cache, and search index. If the image exists correctly in target storage but is not displayed, correct the target-side presentation layer instead of starting another migration activity.

9. Apply the narrowest verified correction

   Correct only the confirmed source-access, source-file, target-acceptance, association, processing, or presentation cause. Preserve the original evidence and test the same samples again.

Choose the correction by cause

Confirmed cause	Safest corrective path
Source image file is missing or corrupt	Restore or replace the source asset through the source platform’s supported process, preserve the source record relationship, and verify the file before future processing.
Image URL is expired, private, signed, or authentication-dependent	Provide stable supported access through the approved connection or export method. Do not publish private assets or share credentials in a ticket.
CDN, firewall, bot protection, hotlink protection, or hosting policy blocks access	Ask the responsible owner to review the specific request, host, path, timestamp, and response. Make the smallest approved access change and retest.
Custom local path or incomplete source export omits files	Correct the supported KitConnect, source-file, folder, permission, or transfer setup through Troubleshoot Connection Setup.
Target rejects the format, size, dimensions, or filename	Confirm the target platform’s current requirement and use a supported source asset or approved target-side media process. Avoid bulk conversion until representative samples pass.
Parent record or relationship failed	Resolve the affected record, dependency, or mapping issue first. Then verify that the image associates with the corrected target record.
Image is attached to the wrong record or variant	Preserve both source and target identifiers, review duplicate records and relationship keys, and correct the responsible mapping or Customization rule before further processing.
Target admin contains the image but the storefront does not	Correct the target theme, channel, publication state, template, cache, index, or presentation condition. The migration result may already be correct.
Target image derivative or thumbnail generation failed	Use the target platform’s supported media regeneration, indexing, or storage recovery process after confirming that the original image is valid.
The issue is unexplained after verified access and target checks	Preserve the activity, sample identifiers, source image locations, target media evidence, and error details, then submit a ticket before broad manual repair.

Manual image replacement can hide a repeatable migration issue

A one-off target edit may make a sample look correct while the same source path, format, association, or access problem remains for other records. Classify the pattern and preserve evidence before manual correction.

Verify the correction

Verification area	Pass condition
Source availability	Each sampled source image exists, is readable through the supported setup, and belongs to the correct source record.
Target storage	The target contains a usable media result in the approved format and location.
Record association	Primary, gallery, variant, Category, CMS Page, and Blog Post images are attached to the correct target records where applicable.
Presentation	Images appear in the required admin, storefront, language, site, and channel contexts.
Image roles	Primary images, gallery order, thumbnails, and applicable content-image roles match the approved target behavior.
Quality	Required images are legible and not unexpectedly corrupted, rotated, or materially degraded. Approved target resizing or cropping is documented.
Scope	Working and failing samples from different paths, formats, sizes, and record types have been retested.
Stability	The corrected result remains available after cache refresh, indexing, media processing, or the relevant operating cycle.

Evidence to collect for support

When the issue remains unresolved, provide:

• the purchased service and migration path;
• the relevant migration activity, date, and History entry;
• affected data type and target environment;
• representative source and target record identifiers;
• the expected image role and actual result;
• source image host or path with sensitive query values removed;
• file type, approximate size, and dimensions where relevant;
• whether the source image opens through the supported setup;
• whether the image appears in target admin, storage, storefront, and required channels;
• Success, Failed, Skipped, and migration-log evidence where available;
• masked screenshots or response details showing the failure;
• changes already tested and their results.

Do not attach passwords, full tokens, private keys, signed URLs containing secrets, payment-card data, or unnecessary personal information.

When to escalate

Use Tickets when:

• the source image is accessible through the supported setup but Next-Cart does not process it as expected;
• a supported target format or size fails repeatedly after representative verification;
• correct parent records receive incorrect image associations;
• the failure affects many records that share no clear source or target pattern;
• the required correction may expose private media or weaken security controls;
• platform-specific hosting or media behavior requires expert analysis;
• approved Customization produces an image result that differs from its requirement;
• destructive or large-scale target repair would be required.

Prevent image issues

• keep required source images available and associated with stable source records until validation is complete;
• preserve original source exports and image folders;
• avoid short-lived signed image URLs for migration input where a stable supported method is available;
• identify CDN, firewall, authentication, and hotlink requirements before migration;
• include large, unusual, multi-image, and externally hosted assets in Demo and Full Migration samples;
• document expected primary, gallery, variant, and content-image relationships;
• validate both target admin storage and storefront presentation;
• coordinate target theme, cache, indexing, and media-processing work with migration validation.

Next step

After the correction, repeat the affected checks in Validate Products and Categories or Validate Content, URLs, and Redirects, depending on the record type.

When the parent record or relationship is absent, continue with Missing Data. When images are associated with duplicate target records, continue with Duplicate Data.