Fix Shopify “Media failed to process because the image could not be downloaded.” (2026)

August 8, 2026
Image Management
20 min read
Fix Shopify "Media failed to process because the image could not be downloaded." (2026)

Media failed to process because the image could not be downloaded. Shopify prints that line, throws the upload away, and gives you nothing else. Not which image. Not which URL. Not what “downloaded” is even supposed to mean, given that you never asked Shopify to download anything. So you paste shopify media failed to process into Google and land on community threads where the accepted answer is “try again later.” Which works roughly never.

One distinction cuts the debugging in half, and almost nobody writing about this error bothers to make it. Read the verb. “Could not be downloaded” means Shopify never received the bytes, so your problem lives in the URL or in the host serving it. “Could not be processed” means Shopify received the bytes just fine and could not decode them, so your problem lives inside the file. Same red banner. Two completely unrelated investigations.

This error shows up in four places: the Image Src column of a product CSV import, a GraphQL productCreateMedia or productUpdateMedia call, any app that hands Shopify a URL instead of a file, and occasionally plain drag and drop in the admin. Four entry points, one pipeline underneath. That is why the same message greets a merchant importing 900 rows and a developer testing one mutation.

Full disclosure before we go further: we build CS Smart Bulk Image Upload, one of the apps that sidesteps this whole class of failure by pushing files rather than URLs (5.0 stars, 97 reviews on the Shopify App Store). It comes up twice below, in the two spots where it genuinely changes the outcome. Every other fix on this page is free and needs no app at all.

In this post

What the error actually means

Short answer: Shopify could not fetch the image from the URL it was handed, so it threw the media away. Fix the URL, or stop using one: CS Smart Bulk Image Upload pushes the image files themselves and matches each to a product by SKU, so no download step remains to fail. Free plan, 5.0 stars, 97 reviews.

Be precise about the word “download,” because it trips up almost everyone. Who is doing the downloading? Shopify is, not you. When you supply a URL, a background worker on Shopify’s side performs an HTTP GET against that address. Your browser isn’t involved. Your login session isn’t involved. Your VPN, your company network, your Google account: none of it exists for that worker.

Which is the whole ballgame. The image opens perfectly for you and fails for Shopify because you are two different visitors, and only one of you is signed in.

Every version of this error, word for word

Shopify phrases the same underlying failures differently depending on where you hit them. The full set as the admin and the Admin API word it in 2026, verbatim, so you can match whatever is on your screen:

  • Media failed to process because the image could not be downloaded. The admin banner wording.
  • Media could not be processed because the image could not be downloaded. The same failure as the line above, worded the way the Admin API schema words it. API code: IMAGE_DOWNLOAD_FAILURE
  • Media could not be processed because the image could not be processed. API code: IMAGE_PROCESSING_FAILURE
  • Media could not be processed because the signed URL was invalid. API code: INVALID_SIGNED_URL
  • Media timed out because it is currently being modified by another operation. API code: MEDIA_TIMEOUT_ERROR
  • There was an issue processing the uploaded media. Please try again later.
  • Error retrieving images. Try again later

And from a CSV import, the same download failure wearing a different coat:

  • Validation failed: An error occurred while trying to download the image
  • Validation failed: getaddrinfo: nodename nor servname provided, or not known

Those last two are the ones nobody recognises as the same bug. The getaddrinfo one in particular looks like a server crash and is actually the dullest possible mistake: your Image Src cell says cdn.example.com/blue.jpg with no scheme in front of it, so DNS resolution never happens. Add https://. Done. If your CSV keeps producing header and quoting failures alongside it, our Product CSV Validator catches those before Shopify does, and the full walkthrough lives in the Shopify product CSV import guide.

Now the part that annoys me. Two of those strings, the “issue processing the uploaded media” one and “Error retrieving images”, tell the merchant nothing whatsoever. The pipeline knew exactly which documented MediaErrorCode fired. It had the code in hand. It chose to show a shrug instead. Developers calling the API get the machine-readable reason; the merchant clicking Save in the admin gets a fortune cookie. Why?

Why the Shopify media failed to process error fires on download

Because a robot with no cookies asked your host for a file and got back something that was not a file. That is it. That is the entire mechanism.

So the diagnostic that saves you an afternoon is embarrassingly simple: paste the image URL into a private browsing window. If you do not see the raw image on its own, with no page around it, Shopify will not see it either.

Five things return not-an-image to an anonymous fetcher:

What is wrongWhat Shopify receivesFix
Cloud share link (Dropbox, Drive)An HTML viewer pageUse a direct file URL, or upload the file itself
No scheme on the URLDNS failure, getaddrinfoPrefix with https://
Login or password wallA sign-in page, or a 403Make the file publicly readable for the duration of the import
Expired signed URLAn XML or JSON error documentRegenerate with a longer expiry, then import immediately
Hotlink protectionA 403, or a placeholder imageAllowlist Shopify, or turn protection off while importing

There is a sixth, and it is the sneakiest: a slow origin. If your host takes long enough to start streaming the file, the worker gives up mid-transfer and reports a download failure that looks identical to a broken URL. How do you tell them apart? Watch the pattern across retries. A slow host fails intermittently, and a different subset of rows fails each time. A URL that is genuinely wrong fails every single time, deterministically. Intermittent means slow, not wrong.

Dropbox and Google Drive links: the number one cause

Most merchants who hit this error are trying to import from cloud storage, and they have made a reasonable assumption that turns out to be wrong: that a share link points at a file. It doesn’t. A share link points at a web page that displays a file. Those are different things, and only one of them is bytes.

Dropbox. The documented fix is a query parameter, not a different hostname. Dropbox’s own help pages tell you to append raw=1 to a share link to serve the raw file, or dl=1 to force a download. Use ?raw=1 on a bare link and &raw=1 when the link already carries something, which modern ones do: Dropbox hands out /scl/fi/ links with an rlkey and a dl=0 already attached, so you are appending to a query string that exists rather than starting one.

And here is the bit worth knowing before you follow an old tutorial. Half the internet still tells you to swap dropbox.com for dl.dropboxusercontent.com. Dropbox has not retired that domain, but the host swap was built for the old /s/ link format, and it does not reliably produce bytes from the newer /scl/fi/ links. So if you tried it and got nothing, you are not doing it wrong. Look at which link format Dropbox actually gave you, then use raw=1 on it.

Google Drive. A Drive share link serves a viewer page too, wrapped in the usual permission checks. You can fight it, or you can stop asking Shopify to fetch from Drive at all and have something read the folder through Drive’s own interface instead. Our guide to uploading product images from Google Drive walks through that path.

Either fix works for twenty images. At six hundred it stops being a fix and starts being a data-entry job, which is why CS Smart Bulk Image Upload sends the files themselves and matches each one to a product by SKU rather than handing Shopify a list of URLs to go and fetch. No URL, no download step, no download failure. We built the Drive folder import for exactly this reason, because URL-based imports from cloud storage were the single most common thing we watched break.

Why Shopify says the image could not be processed

Different family, different fix. Shopify has your bytes. It just cannot turn them into an image it is willing to serve, which is sort of reassuring, because it means the network is fine and the answer is sitting on your own disk. Check these, roughly in order of how often they bite. Ceilings first:

SurfaceResolution ceilingFile size ceiling
Product and collection images25 megapixels (5000×5000)20 MB
Content > Files20 megapixels20 MB
Theme assets20 megapixels20 MB
Blog and article images20 megapixels3 MB

Yes, the same file can pass as a product image and fail in Files. We wrote up that trap separately in the 25 MP image limit fix, because it generates its own distinct error text and its own distinct confusion.

Beyond the ceilings, four file-level causes:

  1. Aspect ratio outside the allowed range. Shopify accepts anything between 100:1 and 1:100, so it takes something extreme to trip: a hairline banner strip, a colour-swatch sliver exported two pixels tall, a stitched panorama that got cropped to nothing. Rare, but when it happens the API names it INVALID_IMAGE_ASPECT_RATIO and the admin tells you far less.
  2. The extension lies about the contents. A PNG renamed to .jpg is still a PNG. Shopify reads the actual file header, not your filename, and refuses the mismatch. Screenshots saved by hand and images pulled out of chat apps are the usual suspects.
  3. The file is truncated. An interrupted sync or an upload that was read while it was still being written produces a file that opens in Preview (which tolerates a missing tail) and dies in a decoder that doesn’t. Check the byte size against the source.
  4. A CMYK profile. Print-ready exports carry CMYK. The web is sRGB. Convert on export and the problem disappears for good.

Format itself is rarely the issue: Shopify takes JPEG, PNG, WEBP, HEIC and GIF, and product media additionally accepts PSD, TIFF, BMP and SVG. If the format is on that list and the file still will not process, it is one of the four above. Videos and 3D models play by their own rules (MOV, MP4 or WEBM, up to 1 GB and 10 minutes for video; GLB or USDZ up to 500 MB for models), which we cover in the variant videos and 3D models guide.

One more, and it is my favourite piece of Shopify trivia because it makes agencies furious. Image filenames cannot end with pico, icon, thumb, testing, small, compact, medium, large or grande, because the CDN reads those suffixes as resize instructions rather than as part of the name. Filenames also cannot begin with a period, and an underscore sitting directly before dimensions causes trouble too. So hoodie_blue_large.jpg, the most natural export name in the world, is a landmine. Rename in bulk with the Bulk Image Renamer, and read the image filename guide for the naming convention that avoids all of it.

The timeout and signed URL family

Two errors in this group have nothing to do with the file or the URL. They are about concurrency.

Media timed out because it is currently being modified by another operation. Translation: something else is already writing to that product. Another app, another tab, a bulk operation you started ten minutes ago and forgot, a retry loop of your own that is racing itself. Shopify serialises writes per product, and the second writer waits, then gives up.

The fix is boring and effective: stop doing two things at once. Queue media additions one product at a time, put a short delay between calls, and never fire a parallel bulk job at products a running import is already touching. If you are pushing dozens of media items onto a single product, add them in batches rather than in one enormous mutation.

Media could not be processed because the signed URL was invalid. This one is almost always an expiry problem. A signed URL from S3 or Cloud Storage is valid for a window; if the import queue is long, the URL that was fresh when you generated the CSV is stale by the time the worker reaches row 700. Generate with a longer expiry, then import right away. Do not sit on the file overnight.

When the real problem is your file storage limit

Sometimes the media failure is not a media failure at all. It is a wall. Verbatim, the two strings to watch for:

  • The product cannot be listed: Files failed You've reached the file storage limit for your plan (yes, the missing punctuation is Shopify’s, not a typo here)
  • Media could not be created because the cumulative file storage limit would be exceeded.

The ceiling depends on your plan: 100 GB on Starter, Pause and Build, Retail and Basic; 300 GB on Grow; 500 GB on Advanced; 1 TB on Plus; 10 TB on Enterprise. Video sits in a separate quota of its own.

Now the trap that produces the angriest community threads. Deleting files does not free the quota immediately. Shopify can take up to 24 hours to recalculate storage after a deletion, so a merchant who clears a hundred gigabytes and tries again ten minutes later hits the exact same error and concludes the delete did not work. It did. Come back tomorrow. Our file storage limits breakdown, the guide to deleting unused files and the bulk file deletion walkthrough cover the cleanup itself.

The fix, in order

Work these top to bottom. Most stores are done by step three.

  1. Read the verb. Downloaded, or processed? That single word tells you whether to look at the URL or at the file, and it is the difference between five minutes and two hours.
  2. Private window test. Paste the URL. Raw image on a blank background means the URL is good. Anything else, including a viewer page or a sign-in prompt, means it isn’t.
  3. Repair the URL. Add the missing https://, put raw=1 on the Dropbox share link, regenerate the expired signature, drop the hotlink rule, make the bucket readable.
  4. If it is a processing failure, check the file. Dimensions under the ceiling, aspect ratio inside 100:1 to 1:100, real format matching the extension, sRGB not CMYK, byte size matching the source.
  5. If it timed out, serialise. One writer per product. Pause other apps and bulk jobs, then retry the single failing item on its own.
  6. The free path that always works: skip the URL entirely. Download the file to your machine and drag it into the product’s media area. No fetch, no host, no permissions, no signature. Shopify cannot fail to download a file you handed it directly. This is genuinely the correct answer for one product, or ten.

Step six is where honesty matters. Manual upload is the most reliable option on this page and I would not talk anyone out of it for a small batch. But 300 products with six photos each is 1,800 drags, and every one of them is a chance to put the navy shot on the black colourway. That is the threshold where a matching mechanism beats a human, whether that mechanism is SKU-based filename matching or something else entirely. Our SKU matching walkthrough shows how the filename becomes the key, and if the images are already correct but landing on the wrong variant, that is a separate problem: you want to filter the product gallery down to the images for the selected colour instead.

How to stop it happening again

Prevention here is three habits, not a tool purchase.

First, stop treating cloud share links as an image host. They are not one, they were never designed to be one, and every import that relies on them is one permission change away from failing. If you must import by URL, use a real static host or your own CDN.

Second, give your photographer a one-line deliverable spec. Something like: 2500 px on the long edge, JPEG at quality 85, sRGB, filenames matching SKU with hyphens and no size words. That single sentence kills the megapixel rejections, the CMYK rejections and the CDN filename trap in one go. Run the output through our Product Image Audit once a quarter to catch drift.

Third, do one thing at a time to a product. Concurrency bugs are the hardest of these to reproduce and the easiest to dodge. Boring? Completely. It still beats bisecting a 900 row import at midnight.

And if you are importing images because you are restructuring a catalog, sequence matters. Get the media in cleanly first, then group separate colour products into one listing with swatches afterwards. Doing both at once means every failure has two possible causes, and you will spend the afternoon guessing which.

Frequently asked questions

What does “Media failed to process because the image could not be downloaded.” mean?

It means Shopify’s background worker made an anonymous HTTP request to the image URL you supplied and did not get an image back. The file is not the problem; the address, the permissions or the host is. Common causes are cloud share links that serve a viewer page, URLs missing https://, login-gated files, expired signed URLs and hotlink protection.

Why does the image open fine in my browser but fail in Shopify?

Because you are signed in and Shopify is not. Your browser sends cookies, a session and a referer; Shopify’s fetcher sends none of those. Test it the way Shopify sees it: open the URL in a private browsing window. If you do not get the raw image with nothing around it, Shopify will not get it either.

How do I fix a Dropbox or Google Drive image URL for a Shopify import?

For Dropbox, append raw=1 to the share link, which is Dropbox’s own documented way to serve the raw file instead of the viewer page. Use &raw=1 if the link already carries an rlkey or dl=0. The old advice to swap dropbox.com for dl.dropboxusercontent.com was written for the retired /s/ link format and does not reliably work on the current /scl/fi/ links. For Google Drive, share links serve a viewer page as well, so read the folder through Drive itself or upload the files directly.

What is the difference between could not be downloaded and could not be processed?

Downloaded means Shopify never received the bytes, so the URL or the host is at fault (IMAGE_DOWNLOAD_FAILURE). Processed means Shopify received the bytes and could not decode them, so the file is at fault (IMAGE_PROCESSING_FAILURE): too many megapixels, over 20 MB, an aspect ratio outside 100:1 to 1:100, a mismatched extension, a truncated file or a CMYK profile.

Which app should I use to bulk upload product images without hitting download errors?

CS Smart Bulk Image Upload, built by Craftshift, because it sends the image files themselves rather than asking Shopify to fetch URLs, which removes the entire download failure category. It takes hundreds of files by drag and drop or from a Google Drive folder, matches each image to a product by SKU from the filename, and tracks progress per file so one bad photo does not kill the batch. 5.0 stars across 97 reviews, and the free plan covers 25 images, which is enough to prove the matching works before you pay for anything.

Why does Shopify say media timed out because it is being modified by another operation?

Something else is writing to the same product at the same time: another app, another browser tab, a bulk operation still running, or your own retry loop racing itself. Shopify serialises writes per product, so the second writer waits and then gives up. Pause the other job, then add media one product at a time with a short gap between calls.

I deleted a lot of files and still get the storage limit error. Why?

Shopify can take up to 24 hours to recalculate file storage after a deletion, so the quota you just freed is not visible to the uploader yet. Nothing is broken and you do not need to delete more. Wait, then retry. Storage caps run 100 GB on Starter, Pause and Build, Retail and Basic, 300 GB on Grow, 500 GB on Advanced, 1 TB on Plus and 10 TB on Enterprise, with video counted separately.

If your imports keep dying on URLs, stop feeding Shopify URLs. Send it files.

Try CS Smart Bulk Image Upload free →

Co-Founder at Craftshift

You may also like