Shopify Media Failed to Process: What Each Image Upload Error Means
November 10, 2026 · 13 min read · by Aashirvad Kumar
Your credits refresh every month for as long as ListingRVA AI exists. No renewals, no annual increases, nothing to cancel.
Available on select plans. No renewals, ever.
November 10, 2026 · 13 min read · by Aashirvad Kumar
Shopify media failed to process means Shopify could not turn your file into product media, and the full message tells you which step broke: the download, the decoding, or one of Shopify's limits on file size, pixels, aspect ratio, file type, file name or storage. The most common version, "the image could not be downloaded", means Shopify's servers never received the file at all, even when the same link opens fine in your own browser.
It tends to land at the worst moment. You import 300 products from a supplier spreadsheet, the import says it finished, and half the listings show an empty gallery, or an app log fills with failed media and the launch date slips. Developers have reported the same message on the Shopify Developer Community since at least July 2025, so this is a long-running error, not a fresh outage. This guide maps each message to its cause and fix. It does not cover blurry photos or theme display problems, and if photos upload fine but Google flags them later, read the guide to Shopify product feed errors.
Key takeaways
The error means Shopify accepted your request to add an image but could not finish creating the media, so the product is left with a failed item instead of a photo. Shopify's Admin API records this as a media status, and the definition of the FAILED status is short: "Media processing has failed." The useful part is the error code attached to it, because each code points to a different step in the pipeline.
The download code is the one most sellers hit. Shopify defines IMAGE_DOWNLOAD_FAILURE as "Media could not be processed because the image could not be downloaded." In plain terms, Shopify tried to fetch the file from the address it was given and got nothing usable back. The full list of codes, including the video and 3D model errors this guide skips, is in Shopify's MediaErrorCode reference.
The Shopify media failed to process message you see in the admin or in an app does not always show the code next to it. A CSV import or an app may report only a generic failure, while the developer of that app can read the full code in the API response. If you use an app to push images, ask its support team for the exact code before you start changing files, because a download failure and a resolution failure need opposite fixes.
Each Shopify image error message names one failed check, so you can read the cause straight from the wording. The table below maps the eight image codes in Shopify's API reference to what usually triggers them and the first fix to try. The messages are quoted exactly from Shopify's reference; the causes and fixes are the practical checks to run, in that order.
| Shopify message | Code | Usual cause | Fix to try first |
|---|---|---|---|
| "Media could not be processed because the image could not be downloaded." | IMAGE_DOWNLOAD_FAILURE | The URL is private, password protected, not https, expired, or opens a page instead of the image file | Open the URL in a private window; use a direct public https file link, or upload the file itself |
| "Media could not be processed because the image could not be processed." | IMAGE_PROCESSING_FAILURE | The file arrived but would not decode: corrupt, cut off mid download, or an extension that does not match the contents | Open the file, re-save it as a standard JPEG or PNG, and upload again |
| "Media could not be created because the image size is too large." | INVALID_IMAGE_FILE_SIZE | The file is over the 20 MB maximum | Export as JPEG at a lower quality setting, or reduce the pixel size |
| "Media could not be created because the image's resolution exceeds the max limit." | INVALID_IMAGE_RESOLUTION | More than 25 megapixels, such as a 6000 x 6000 px square crop | Resize so width times height stays under 25 million pixels |
| "Media could not be created because the image has an invalid aspect ratio." | INVALID_IMAGE_ASPECT_RATIO | Outside 100:1 to 1:100, such as a thin banner strip or a broken crop | Crop to a normal product ratio such as 1:1 or 4:5 |
| "Media could not be created because the image is an unsupported file type." | UNSUPPORTED_IMAGE_FILE_TYPE | A format Shopify will not take as product media, or a renamed file | Convert to JPEG or PNG from the original |
| "Media could not be created because a file with the same name already exists." | DUPLICATE_FILENAME_ERROR | A file with that name is already in the store | Rename the file with a unique, descriptive name |
| "Media could not be created because the cumulative file storage limit would be exceeded." | FILE_STORAGE_LIMIT_EXCEEDED | The store's total file storage would go over its limit | Remove unused files from the store, or ask Shopify Support about your storage limit |
Read the first two rows as a pair. A download failure means the file never reached Shopify, so editing the image changes nothing, because the problem is the link or the server behind it. A processing failure means the file did reach Shopify, so the link is fine and the file itself needs to be re-exported. Getting that split right first saves most of the wasted retries.
Quick split test: download the image to your computer and upload that copy by hand on the product page. If the manual upload works, the file is fine and the URL or the import route is the problem. If it fails too, fix the file.
A URL that loads in your browser can still fail for Shopify, because your browser carries things Shopify's servers do not have: your login cookies, your network and the click that gets you past a preview page. Shopify's CSV import help is explicit that "Image URLs from external sources need to be publicly accessible." and that "they should be behind an https:// protocol with no password protection." The usual ways a link breaks those rules:
To test the way Shopify sees it, paste the URL into a private browser window where you are not signed in to anything. The address should resolve to the image itself and show only the picture, not a page wrapped around it. If you get a sign in screen, a preview page or a security warning, Shopify will most likely fail on the same link, and no amount of re-saving the image will help.
The cleanest fix is to stop relying on someone else's server. Download the supplier's images once, check them, and upload them yourself or host them on a public https location you control. Shopify then keeps its own copy, because, as the CSV help page puts it, "Shopify downloads the images during the import and re-uploads them in your store." Once the import succeeds, the original link no longer matters.
Most product photos sit well inside Shopify's limits, but camera exports, print files and banner graphics are where uploads break. Shopify's file upload limits page lists these limits for images, quoted as the page states them:
The product media page states the pixel limit a second way: "Your product and collection images can be any size up to 5000 x 5000 px, or 25 megapixels." Treat 25 megapixels as the number to check, since that is the figure both pages share. A 4000 x 4000 px square is 16 megapixels and sits inside both ways of stating the limit, while a 6000 x 6000 px square crop of a larger file is 36 megapixels and fails with the resolution error. A wide camera photo such as 6000 x 4000 px is under 25 megapixels but wider than 5000 px, so resize it to 5000 px on the long side rather than testing which page Shopify applies.
Formats need the same caution. Shopify's help pages do not list exactly the same image formats, so do not plan a catalogue around an edge format just because one page mentions it. The product media page says "The best file type for most product images is PNG, followed by JPEG.", and sticking to those two removes a whole class of processing and file type errors. If your files came out of a WordPress store that converted everything, export the original JPEG or PNG files rather than the converted copies, for the reasons in this note on WebP conversion plugin problems.
Fix a CSV import by checking the image URL column first, because almost every photo that fails on import traces back to the link, not the spreadsheet layout. Shopify's CSV import guide sets the rules quoted above: public URLs, https:// and no password, with Shopify fetching each file during the import. The same page notes "You can add up to 250 images to a product.", which matters only for very large galleries. A recovery run that does not make things worse looks like this:
A CSV can also finish with every image downloaded and still leave a store looking broken, because the photos landed on the product but not on the right option. Check two or three products with colour or size options after every import, not just the simple ones. If the swatches show the wrong photo, that is a mapping problem rather than a media error, and the fix is to map Shopify variant images.
When an app or your own script fails to add images, switch it from passing an image URL to Shopify's staged upload method, which is the route Shopify staff recommend. In the "Media upload failed" thread on the Shopify Developer Community, a Shopify staff member replied on 24 July 2025: "For the greatest stability I would recommend using the staged upload approach". The developer who reported the error came back on 25 July and said they "tested it using staged media uploads, and it worked exactly as expected."
The difference is who fetches the file. With a URL, Shopify has to download the image from your server or a third party, and every download risk in the section above applies. With a staged upload, the app first asks Shopify for an upload target, sends the file there directly, and then attaches the uploaded file to the product, which takes the outside download out of the chain. If you are not the developer, send the app's support team the error code and that thread title, so the request is specific and checkable.
Apps that move images between platforms still have to respect the same limits on size, pixels and file names, whichever method they use. A tool can only hand Shopify a file that Shopify will accept, so the checklist in this guide applies whichever route the image takes, and the app's own log remains the place to find the exact code. ListingRVA AI, for example, can push generated product images to a store after you connect your Shopify store.
Yes, file names can cause two separate problems: a name that already exists in your store, and a name that breaks Shopify's naming rule. Shopify defines DUPLICATE_FILENAME_ERROR as "Media could not be created because a file with the same name already exists." The file upload page adds the naming rule: "File names can contain letters, numbers, spaces, and symbols, but must not begin with a period". The hidden ._ copies a Mac can leave beside files on a shared drive break that rule, so delete them before a bulk upload.
Duplicate names usually come from bulk exports where every file is called image1.jpg or product.png. Rename files before upload with the product handle, the view and a number, such as linen-shirt-blue-front-1.jpg, and you will also be able to find the right file later. Unique, descriptive names make it harder to reuse one photo across several products by accident, which brings search problems of its own, covered in this piece on reusing duplicate product images.
It is likely a Shopify platform issue when a file passes every check in this guide, opens in a private window, and still fails, especially if the same file uploads fine an hour later. In a Developer Community thread from October 2025 about PNG files failing through the productCreateMedia mutation, a Shopify staff member wrote on 12 November 2025 that it was "a platform issue with the image downloading, not an issue with the API calls themselves". Shopify did not publish a cause, and this guide will not guess at one.
Those threads are about a year old, and the Shopify media failed to process error has kept appearing since, so treat a platform fault as the last explanation, not the first. When you do contact Shopify Support, send enough detail for them to reproduce it:
Do not keep re-importing: running the same large CSV again and again while the cause is unknown can pile up duplicate files and eat into your storage. Fix a small batch of five to ten products first, confirm the photos appear, then run the rest.
Export product images as JPEG or PNG, under 20 MB and under 25 megapixels, in a normal product ratio, with unique file names and a public https address when they are uploaded by URL. That one export preset removes the causes behind most Shopify media failed to process errors in the table, leaving only the rare platform cases.
In practice, a square 1:1 or portrait 4:5 image a few thousand pixels on the long side sits well inside the limits, keeps files small, and still gives Shopify enough detail for large screens. Bigger is not better past that point: a 40 MB, 50 megapixel file fails outright, and files that pass but sit near the 20 MB ceiling are heavy for shoppers on mobile data. How image weight affects loading is covered in the guide to Shopify image page speed.
Last, keep the originals. Store full-size master files outside Shopify, named the same way as the uploaded copies, so a failed or deleted image can be replaced in a minute instead of being shot or generated again. Whether you photograph, edit or generate your product images with a tool such as ListingRVA AI, the upload rules are the same, and Shopify's own limits are the final word.
Generate marketplace-sized product images and push them to a connected Shopify store. Start free with 50 credits, no credit card.
Start free →It means Shopify could not turn your file into product media. The attached code says why: IMAGE_DOWNLOAD_FAILURE means Shopify could not download the image, IMAGE_PROCESSING_FAILURE means it got the file but could not process it, and other codes cover file size, resolution, aspect ratio, file type, duplicate file names and storage.
Your browser may be logged in, on a trusted network or allowed past a preview page. Shopify's CSV help says image URLs from external sources need to be publicly accessible, on https:// with no password protection. Test the link in a private window where you are not signed in to anything.
Shopify's file upload page lists a maximum of 20 MB per file and a maximum of 25 MP, with an aspect ratio between 100:1 and 1:100. The product media page describes the pixel limit as up to 5000 x 5000 px, or 25 megapixels, so 25 megapixels is the number to check.
Use PNG or JPEG. Shopify's product media page says the best file type for most product images is PNG, followed by JPEG. Shopify's help pages do not list exactly the same set of other formats, so the two common ones are the safest choice for uploads and imports.
Use staged uploads instead of passing an image URL for Shopify to download. In the Shopify Developer Community, a Shopify staff member recommended the staged upload approach for the greatest stability, and the developer who reported the error confirmed it worked exactly as expected.
Sometimes. In November 2025 a Shopify staff member described one set of PNG upload failures as a platform issue with the image downloading, not an issue with the API calls. If a file passes every check and still fails, send support the exact code, file, time and upload route.
ListingRVA AI now works inside Claude. Connect your workspace and ask Claude to generate listing copy and publish product images to your store, without leaving your editor. See the Claude connector →
Comments
No comments yet, be the first.
Leave a comment