Troubleshooting

Troubleshoot a failed image upload

Check the file, upload state, plan capacity, and secure R2 ownership path before retrying.

Last updated: August 4, 2026
Audience: Store owners uploading product, variant, theme, logo, or request images

What you’ll accomplish

The upload stays at zero, stops during progress, returns an error, finishes but the editor cannot save it, or the saved page shows no image.

The file is not a real JPG, PNG, or WebP even if its extension says it is.
The file is too large for the current upload control or connection.
The store or account reached its resolved image capacity.
The browser lost the connection or the editor was closed before the upload finished.
The image was uploaded for a different store/scope and cannot be attached here.
A theme save is still pending or the public page is showing an older saved theme.

1
Identify the exact control.
Product, variant, theme, logo, payment proof, and custom-theme reference uploads use different ownership/scopes.
2
Open the file locally.
Export it again as JPG, PNG, or WebP. Do not rename an SVG, PDF, HEIC, or other file to .jpg.
3
Reduce the dimensions/file size if practical.
Keep enough detail for the storefront but avoid camera-original files when not needed.
4
Retry once on a stable connection.
Keep the page open and wait for 100%/the preview before saving.
5
Check Plan usage for theme-image capacity.
Product and theme image limits are not necessarily the same. Follow the exact limit notice shown by the editor.
6
Refresh only after the editor has saved.
If the upload finished but the public result is missing, confirm the image is still attached in the saved editor.

Do not paste private bucket URLs or storage credentials into support.
Do not repeatedly upload the same large file while earlier attempts are still running.
Do not use another store's uploaded URL.
Do not upload customer PII as a test image.

Copy the store slug, order reference, invoice reference, or request reference shown on the page.
Describe what you expected, what happened, and the last safe step you completed.
Attach a screenshot only after hiding customer names, phone numbers, addresses, payment references, and other private data.
Never send a password, OTP, session link, or full payment-card details.

Contact support when a valid small JPG/PNG/WebP fails twice on a stable connection, or when the editor says capacity is available but rejects the upload.
Include the store slug, page, image purpose, browser/device, approximate file type and size, local time, and the exact non-sensitive error text.