New ListingRVA AI is now in Claude: generate listing copy and publish images by chat. Now in Claude. Set it up →
Lifetime Pay once, never pay for product photography again. Lifetime access on select plans. Pay once, not monthly. See lifetime →
← Blog
Shopify

Shopify Media Failed to Process: What Each Image Upload Error Means

November 10, 2026 · 13 min read · by

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

  • "Image could not be downloaded" means Shopify never got the file: check the URL is public, uses https:// and has no password protection.
  • "Image could not be processed" means the file arrived but would not decode: re-export it as a plain JPEG or PNG.
  • Keep each file under 20 MB and 25 megapixels, inside an aspect ratio of 100:1, with a unique name that does not begin with a period.
  • For apps and API uploads, Shopify staff recommend the staged upload approach for the greatest stability.
  • Some failures are a Shopify platform download issue: retry a small batch, then send support the code, file and time.
Also ReadShopify Magic Product Images vs a Dedicated AI Studio: The Honest Difference
›
Map of six Shopify image upload error messages to their usual cause and first fix, from could not be downloaded to duplicate file name.

What does the Shopify media failed to process error mean?

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.

Also ReadShopify Bulk Edit Product Descriptions: Rewrite 200 Without Duplicates
›

Which Shopify image error message points to which cause?

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 messageCodeUsual causeFix to try first
"Media could not be processed because the image could not be downloaded."IMAGE_DOWNLOAD_FAILUREThe URL is private, password protected, not https, expired, or opens a page instead of the image fileOpen 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_FAILUREThe file arrived but would not decode: corrupt, cut off mid download, or an extension that does not match the contentsOpen 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_SIZEThe file is over the 20 MB maximumExport 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_RESOLUTIONMore than 25 megapixels, such as a 6000 x 6000 px square cropResize 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_RATIOOutside 100:1 to 1:100, such as a thin banner strip or a broken cropCrop 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_TYPEA format Shopify will not take as product media, or a renamed fileConvert to JPEG or PNG from the original
"Media could not be created because a file with the same name already exists."DUPLICATE_FILENAME_ERRORA file with that name is already in the storeRename the file with a unique, descriptive name
"Media could not be created because the cumulative file storage limit would be exceeded."FILE_STORAGE_LIMIT_EXCEEDEDThe store's total file storage would go over its limitRemove 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.

Why does the image URL load in my browser but Shopify cannot download it?

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:

  • A cloud drive or file share link that opens a preview page with a download button instead of the raw image file.
  • A staging site, private store or supplier portal behind a password, a login wall or an IP allowlist.
  • A plain http:// address, or an https:// address whose security certificate has expired.
  • A signed or temporary link that expired before Shopify fetched it, which is easy to hit on a long import.
  • A supplier server that blocks automated downloads or limits how many files one visitor can pull at once.

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.

Also ReadGoogle Indexing the Wrong Shopify Product URL? Duplicate-Content Fix
›

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.

Six-step pre-upload checklist for Shopify product images: JPEG or PNG, under 20 MB, under 25 megapixels, sane aspect ratio, public https URL and unique file name.

Are your images inside Shopify's size, pixel and format limits?

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:

  • File size: "Maximum of 20 MB (megabytes)"
  • Resolution: "Maximum of 25 MP (megapixels)"
  • Aspect ratio: "Between 100:1 and 1:100"
  • Formats listed on that page: "JPEG, PNG, WEBP, HEIC, and GIF"

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.

How do you fix image failures in a CSV import?

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:

  1. Filter the products that came in without images and copy only those rows into a new, small CSV.
  2. Open five of their image URLs in a private window. If all five fail, the host is the problem; if only some fail, look at those files.
  3. Replace preview or share links with direct file links, or re-host the images on a public https location.
  4. Check that every file is a JPEG or PNG under 20 MB and under 25 megapixels, with a normal aspect ratio.
  5. Import the small CSV so it updates the matching products, then open ten of them and confirm the photos appear.

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.

What do you do when an app or API upload fails?

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.

Does the file name or a duplicate name cause an error?

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.

When is it a Shopify platform issue, and what do you tell support?

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:

  • The exact message and code, copied rather than paraphrased.
  • The product, the image URL or file name, and the time of the failed attempt with your time zone.
  • Whether the same file uploads by hand in the admin.
  • The upload route: admin, CSV import, a named app, or your own API call.
  • Whether the failure repeats on every attempt or only on some of them.

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.

How do you export images so they upload cleanly the first time?

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.

Create product images sized for your store

Generate marketplace-sized product images and push them to a connected Shopify store. Start free with 50 credits, no credit card.

Start free →

Frequently asked questions

What does Shopify media failed to process mean?

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.

Why can Shopify not download an image that opens in my browser?

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.

What is the maximum image size Shopify accepts?

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.

Which file format should I use for Shopify product images?

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.

How do I stop image uploads failing in my app or script?

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.

Is a failed image upload ever Shopify's fault?

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.

Keep going

Browse all articles →
New

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 →

Share

Comments

No comments yet, be the first.

Leave a comment

Comments are reviewed before they appear.

Hi! Questions about product photography or your listings? Ask AI anything.