Troubleshooting | Image Upload Problems

Image problems split into three: won't upload, uploaded but won't show, or shows but looks wrong. One section each.

Won't upload

1. Format — use PNG, JPG, WebP or GIF. HEIC (iPhone default) and TIFF need converting first.

2. Size — very large files can fail; export at web size (2000–3000px on the long edge is plenty) rather than straight from a 50MP camera.

3. Allowance — the media quota shows on the upload control (“1999 of 2000 images remaining”). At the limit, clear unused media or upgrade storage.

4. The connection — a flaky upload of a big batch dies quietly mid-list. Smaller batches tell you which file is the problem.

Uploaded but not appearing

• Product images attach to the product — files sitting in the media library aren't on any product until added in the editor (Title & media → Add media → pick from library).

• Import-by-URL images: the import fetches from the URL when it runs. Blocked hotlinking or a dead old site means silent skips (see the CSV import troubleshooting guide).

Appears but looks wrong

• Cropped oddly — storefronts crop to consistent aspect ratios. Upload square images for catalogue consistency and the problem mostly vanishes.

• Blurry on retina screens — upload at 2× display size; the storefront scales down crisply.

Tips

• Rename files meaningfully before upload (oak-chair-side.webp) — the filename feeds alt-text workflows and your own sanity in the library.