Images Aren't Loading

If your gallery is rendering but the images themselves appear broken, slow, or missing, the issue is usually one of three things: a temporary processing delay, a browser cache, or a storage limit. Each one has a quick fix.

Slow First Load

When you upload a new image, the app processes it in the background to generate optimized versions for the storefront. For a few seconds after upload, the image may take longer to appear:

• Wait 10-30 seconds after uploading before checking the storefront.
• Refresh the page - The processed image should now load quickly.
• Subsequent loads are fast - Once processed and cached, images load just as quickly as any other Shopify image.

Browser Cache

If you replaced or re-uploaded an image but your browser is showing the old one:

• Hard refresh your storefront - Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows. This bypasses your browser's cache.
• Open the page in an incognito or private window - No cache at all, so you see exactly what new visitors see.
• Wait a few minutes for CDN caching to refresh if a hard refresh doesn't help.

Storage Limit Reached

If new uploads are failing or images are missing, check your storage:

• Open any gallery in the app - The storage remaining indicator is shown above the upload zone.
• If you're at the limit, delete unused images from your library to free up space, or upgrade your plan.
• Compress large images before uploading - Most photos look great at 1200-1600 px wide and use much less storage than full-resolution camera files.

Images Deleted from the Library

If an image was deleted from your library (rather than just removed from a single gallery), it's gone everywhere it was used. The gallery will simply skip those images on the storefront:

• Open the gallery in the app to check whether the expected images are still there.
• If images are missing, re-upload them or pick replacements from the library.

Image Doesn't Look Right (Cropping, Aspect Ratio)

If the image loads but looks cropped or stretched in a way you didn't expect:

• Grid crops to the shape you chose - Set Grid tile shape in the block settings to Square, Portrait, Landscape, or Original ratio. Original ratio is the one that doesn't crop at all.
• Mosaic and Collage crop to fill their tiles - Both use fixed tile shapes so the pattern holds together, so images are cropped to fit. This is by design.
• Masonry preserves the natural aspect ratio - No cropping. Switch the gallery to Masonry if you want every image's full proportions to show.
• Carousel - Carousel height is on Adapt to image by default, which never crops. If your carousel is cropping, the block is set to Fixed height: either switch back to Adapt to image, or set Image fit to Fit (original ratio).

Layout is set on the gallery page in the app; Grid tile shape, Carousel height, and Image fit are block settings in the theme editor.