Shopify limits product images to 20 MB and 20 megapixels; the app resizes larger images automatically. Most matching problems come from duplicate identifiers, empty identifiers or small naming slips, all visible in the preview before you upload.
Limits
| Limit | Value | What the app does |
|---|---|---|
| Image file size | 20 MB (Shopify) | Resizes/re-encodes jpg, jpeg, png, webp, gif. Fails with a clear error only if it still doesn’t fit. |
| Image resolution | 20 megapixels (Shopify) | Downscales to about 18 MP and retries. |
| Images per product | 250 (Shopify) | Shopify’s own limit |
| Free plan | 25 images in total | The job stops with “Free upload limit reached”. |
| Preview tables | 5,000 rows shown each | Counters and CSV export cover the full set. |
| Matching results | Kept 2 hours | Match again if you wait longer. |
| Shopify file rate limit | Shop-wide | Automatic 3 s → 6 s → 12 s backoff and retry. |
Over-limit images are listed in a warning banner on the preview page before you upload.
Recommended specs: JPG or WEBP, 2048–4096 px on the longest edge, sRGB, under 5 MB.
How long large uploads take
Shopify limits how fast files can change in a store, for the whole shop. The app downloads and uploads in parallel and backs off automatically when it reaches the limit, so large jobs run steadily rather than fast. Plan on hours, not minutes, for tens of thousands of images. Progress is saved per image, so a restart resumes where it stopped.
Matching problems
| Symptom | Likely cause | Fix |
|---|---|---|
| All images unmatched | Wrong matching type or folder, or the identifier is empty on your variants | Compare the Expected SKU column with your product data |
| Some images unmatched | Typos, trailing spaces, missing extension, non-numeric suffix | Export the non-matched CSV and compare it with a product export |
| Image matched the wrong variant | Duplicate identifiers, or a “contains” option matching a shorter code | Switch to an exact option or make codes unique |
| Fewer matches with duplicate SKUs | Only the first variant with an identifier is kept | Ask us for multi-variant matching, or make identifiers unique |
| Title matching fails on accents | Accents encoded differently in file names (macOS) and Shopify | Ask us for Unicode normalisation, or match by SKU |
| Edited products still match old values | The catalog is cached | Press Clear cache |
| New images not listed | The folder listing is cached | Press Match again or refresh the folder selector |
| Matching times out | Very large catalog and folder | Ask for a collection filter, or split the folder |
Upload messages
| Message | Meaning | What to do |
|---|---|---|
Image size is larger than 20MB / 20 megapixels | Couldn’t be resized under the limit | Re-export the image smaller |
hit the Shopify file rate limit; retrying in Ns | Normal Shopify throttling | Nothing. The app retries |
Your shop reached Shopify API rate limit | Another app or job is using the API | Avoid running two big jobs at once |
Free upload limit reached | The 25 free images are used | Upgrade your plan |
This folder already in process | A job for the folder is still running | Wait or stop it |
product has only default variant… | Image went to the product, not a variant | Expected behaviour |
Job ends finished with errors | Some images failed | Read the error lines. Failed images are retried automatically |
Pilot checklist
- A single-image product gets one image, set as its variant image.
- A multi-image product gets images in
_0/_1/_2order. - Each variant of a multi-variant product shows its own image.
- Alt text in Shopify matches the preview.
- A deliberately wrong file name appears under “Non matched” and in the CSV.
- Replace mode on a test product leaves exactly the new set.
Getting help
Contact us with your store domain, the folder name, the matching type, roughly when you ran it, and two or three example file names with the SKU or barcode they should have matched. We can record a full trace of a matching run and tell you exactly why an image matched what it did.