Shopify error: “a file with the same name already exists” (2026 fix)

Media could not be created because a file with the same name already exists. That is the entire message. No filename, no link to the file that is blocking you, no hint about which of the 40 photos you just dragged into the product page caused it. Picture an apparel drop where 39 images land and one bounces. Shopify will not tell you which one. It will not tell you where the conflicting file lives either, and in a lot of cases that file is not visible on the page you would think to check.

The same collision has a second wording depending on which surface you hit, and the Admin API has a code name for it. The fix is a rename. That part is easy. Finding the file you are colliding with is the part that eats an afternoon.

Then there’s the quieter half of this problem, and it’s the reason this post exists. Shopify image filenames cannot end with nine specific words, because the CDN reads a trailing size word as a resize instruction rather than part of the name. Odd rule. Very real. Plenty of photographers and agencies export hoodie_blue_large.jpg as a matter of habit, and nobody tells them why that’s a bad idea until something breaks with no explanation attached.

Disclosure before we go further. We’re Craftshift, and we build CS Smart Bulk Image Upload, a Shopify app for pushing hundreds of product images at once. It shows up below, in the places where it genuinely changes the workflow, and nowhere else. For a single collision you don’t need an app at all. The manual fix comes first.

In this post

• Why does Shopify say a file with the same name already exists?
• The exact error strings, and the API error code
• Why it fires, and why the same collision sometimes goes through silently
• How to fix the duplicate filename error today, no app needed
• The second trap: nine words a Shopify image filename cannot end with
• Bad filename versus good filename
• How to rename a file that is already uploaded
• Why filenames matter well beyond this error
• How to stop it happening on the next shoot
• Frequently asked questions
• Related reading

Why does Shopify say a file with the same name already exists?

Short answer: Shopify keeps one filename namespace per shop, so a second image with the same name is refused instead of overwritten. Rename the file, or delete the original in Files first. For a full shoot, CS Smart Bulk Image Upload matches each file to its product by SKU and reports every rejected file rather than failing the batch.

The important word is shop. Not product. Not collection. Your store has one flat pool of filenames, and the filename becomes part of the public CDN path that serves the image. Two files cannot occupy the same path, so the second one is refused. That’s the whole mechanism, and once you see it the error stops feeling random.

The exact error strings, and the API error code

Three wordings, one cause. If you landed here from a search, the string you pasted is one of these:

• Media could not be created because a file with the same name already exists.
• File could not be created because a file with the same name already exists.
• DUPLICATE_FILENAME_ERROR

The first wording is what you get when the upload is attached to product media. The second is the file surface, which is what you hit when the upload goes to Content, Files, or through an app that writes there. DUPLICATE_FILENAME_ERROR is the code name the Admin GraphQL API returns, and it sits in both the MediaErrorCode and FileErrorCode enumerations on shopify.dev with the same sentence and one word swapped. Which is why developers searching the code name and merchants searching the sentence are looking at the same problem from two ends.

Worth knowing if you are debugging an app or a script: the API returns the code, not a friendly sentence, and it doesn’t hand you the identifier of the file you collided with. So an app cannot tell you either. We would love to show you the blocking file. The API does not give it to us.

Why it fires, and why the same collision sometimes goes through silently

This is the bit that makes merchants think their store is broken. The same duplicate name doesn’t behave the same way on every surface. Some upload paths quietly append a unique identifier and the upload succeeds, so you end up with two near identical names and no warning at all. Others refuse the file outright with the error above. Same collision, two behaviours, zero explanation of which one you are about to get.

And that isn’t folklore, it’s a documented switch. The Admin GraphQL fileCreate mutation takes a duplicateResolutionMode argument with exactly two settings: RAISE_ERROR, the default, which produces the message you pasted into Google, and APPEND_UUID, which sticks a unique identifier on the end of the name and lets the file through. Whichever tool performed your upload chose one on your behalf. It didn’t ask. It doesn’t tell you which.

That inconsistency is the actual defect in the experience. Not the uniqueness rule. The rule is fine and every CDN needs one. Being silently forgiven on Monday and hard blocked on Tuesday is what burns the hour.

Now the second half of the mystery: why can you not find the file? Because a file uploaded directly onto a product page does not always show up in Content, Files. The merchant searches the Files list for front.jpg, finds nothing, concludes Shopify is hallucinating, and re-tries the same upload four times. It’s still there. It’s just attached to a product rather than sitting in the library you are searching.

Where do all these identical names come from? Camera and phone defaults, mostly. A camera writes IMG_4021.JPG and DSC_0042.JPG and restarts its counter when the card is formatted. Retouchers work folder by folder, so every product folder gets a front.jpg, a back.jpg, and a detail.jpg. Perfectly sane on a hard drive (the folder path is doing the uniqueness work for you, so the filename never has to). Fatal in a flat namespace, where 300 products means 300 files all wanting to be called front.jpg.

One more trigger that catches people: re-uploading a photo they are certain they already deleted. Usually only one copy went. Deleting the file in Content, Files does nothing to a copy that was uploaded straight onto a product, so the name is still held by the copy you never saw. A separate trap sits next to it and gets blamed for the same symptom: Shopify can take up to 24 hours to recalculate your file storage after a delete, so the storage figure lags and the delete looks like it failed. It didn’t. If you are near a plan ceiling as well, our notes on Shopify file storage limits by plan cover which quota you are actually hitting.

One sanity check before you start renaming anything. Confirm the file type is one Shopify takes at all: product media accepts JPEG, PNG, WEBP, HEIC and GIF, plus PSD, TIFF, BMP and SVG. An unsupported type produces a different message with a different remedy, and merchants sometimes conflate the two. If the wording you got is about a name, you are in the right place.

How to fix the duplicate filename error today, no app needed

Five steps, in the order that wastes the least of your time. All free. None of it needs an app, and if you only ever read one section of this post, read this one.

1. Rename the file on your computer before you upload it again. Give it something that cannot collide: the SKU, the colour, and the shot. ts-1042-navy-front.jpg collides with nothing, ever. This alone clears the error in most cases and takes four seconds.
2. Check whether you actually need a second copy. If it’s genuinely the same photo on a second product, don’t upload it twice. Open Content, Files, copy the existing file URL, and add it to the second product from that URL instead of uploading a second copy. One file, two products, no collision, and you stop paying twice for the same bytes in storage.
3. Hunt the blocking file properly. In Content, Files, search the exact name without the extension. If nothing comes back, the file is attached to a product rather than the library, so search the product catalogue instead, or look at the product you last edited with that shoot. This is the step that people skip and then repeat the failing upload on.
4. Delete the old file only when you are sure it is dead. Deleting a file that a live product or theme section still points at breaks that image on the storefront. Check what references it first. If you are clearing out genuine orphans, our guide to bulk deleting Shopify files walks the safe order.
5. Batch rename the whole folder before the next attempt. Do not fix one file. Fix the export. Our free Bulk Image Renamer takes a list of filenames and applies a pattern across all of them, and the walkthrough for bulk renaming image names covers the find and replace patterns that work on camera output.

A naming pattern that has never failed us, in order: SKU, option value, shot type, index. So ch-8890-walnut-side-01.jpg for furniture, ts-1042-navy-front.jpg for apparel. Boring on purpose. A filename is not branding, it is a key.

That’s the fix, and it costs nothing. Where it stops scaling is arithmetic: 300 products at six shots each is 1,800 filenames you are keeping unique by hand, and a single collision aborts the drag and drop you kicked off ten minutes ago. CS Smart Bulk Image Upload routes each file to the right product by SKU and keeps the batch running when one file is refused, with progress tracking so you can see exactly which files landed. 5.0 stars across 97 reviews on the App Store. We built the error recovery first, before any of the nicer features, because one rejected file out of 400 should never mean starting over.

“Smart Bulk Image Upload worked perfectly for us. We successfully matched and uploaded over 7,000 images, saving an enormous amount of time and manual effort, as we prepare for going live with our store. The app performed exactly as expected, and the developer’s communication was excellent throughout. We’re very pleased with both the app and the support. Highly recommended.”

Onatru, United States, 2026-01-08, CS Smart Bulk Image Upload on the Shopify App Store

The second trap: nine words a Shopify image filename cannot end with

This one is barely documented and it explains a whole category of uploads that fail for no visible reason. As of 2026 it is still one line, in one help article, with no error message anywhere in the admin pointing at it. Nobody warns you. A Shopify image filename cannot end with any of these nine words:

pico, icon, thumb, testing, small, compact, medium, large, grande

Why those nine? Because they’re Shopify’s own size names. The image CDN reads a trailing size word as a rendering instruction, a convention that predates today’s width parameters and still sits in the URL grammar, so hoodie-blue_large.jpg is not a filename as far as the CDN is concerned. It’s a request for the large rendering of something called hoodie-blue. Put a real file there and the grammar collapses, because the name and the instruction are competing for the same characters.

Two more rules in the same family, and both bite silently:

• A filename cannot begin with a period. Obvious once it’s said, easy to hit by accident: macOS drops .DS_Store into every folder, and a hidden file that sneaks into a zip you hand to a developer will fail on the way in.
• Avoid an underscore directly before dimensions. product_image_5x4.jpeg breaks where product-image-5x4.jpeg is fine, because _5x4 reads like a dimension request rather than part of the name. Hyphens are safe. Underscores next to numbers are not.

Now let me be annoyed for a paragraph, because this deserves it. Nine reserved words, one line in one help article, and not a single error message anywhere that says which rule you broke. Nine. A merchant who exports sofa-charcoal-grande.png from a design tool gets a failure or a broken image and no path from the symptom back to the cause. Shopify knows the reserved list, it knows the filename, and it could say so in one sentence. It says nothing. That is a five minute fix on their side that would delete an entire genre of support ticket.

Whose exports contain these words, in practice? Anyone using an image tool with size presets. Photographers who deliver _small and _large pairs for web and print. Agencies whose asset pipeline appends the rendition name to every file it writes. And anyone who saved an image off a Shopify storefront that still serves the legacy size suffixed URLs, so the file landed on their desktop already called something_grande.jpg. That last one is sort of deliciously circular, and we see it more than you would guess.

Bad filename versus good filename

Apparel and furniture, since those two categories generate the most colourway shots per product.

Filename that breaks	What is wrong with it	Filename that works
hoodie_blue_large.jpg	Ends with a reserved size word, and the underscores make it useless as a matching key	hd-2201-blue-front.jpg
oak-dining-table-medium.jpg	Ends with a reserved size word, even though medium describes the table, not the render	dt-4410-oak-6-seat.jpg
sofa-charcoal-grande.png	Ends with a reserved size word (grande is a Shopify rendition name)	sf-1180-charcoal-3-seat.png
swatch_thumb.jpg	Ends with a reserved size word, and says nothing about which swatch	sw-oatmeal-wool.jpg
chair-icon.png	Ends with a reserved size word	ch-8890-walnut-side.png
.linen-cushion.jpg	Begins with a period	cu-3070-sage-linen.jpg
product_image_5x4.jpeg	Underscore directly before dimensions	product-image-5x4.jpeg
front.jpg	Collides with every other product using the same shot label	ts-1042-navy-front.jpg
IMG_4021.JPG	No product meaning, and the counter resets so it collides across shoots	bf-6015-oak-queen-01.jpg

Notice what the right hand column has in common. Lowercase, hyphens only, the SKU in front, the option value in the middle, the shot at the end, and nothing that a resizer could mistake for an instruction. Ugly (deliberately so, because a filename that reads nicely is usually a filename that collides). Run your current library through the Product Image Audit tool if you want to see how much of it follows any convention at all. Most stores we look at have three conventions and a graveyard.

Stores that keep every colourway as its own product need this discipline twice over, because the colour has to be readable in the filename before anything can act on it. That is true whether you are matching images on upload or later grouping separate colour products into one listing with swatches. Sort the names once and every downstream step gets easier.

How to rename a file that is already uploaded

You’re not stuck with a bad name. In Content, Files, open the file and edit its URL Handle, which is the filename portion of the CDN path. Save, and the file serves under the new name.

But one caution, and it matters more than the rename itself: changing the handle changes the public URL. Every place you hardcoded the old one keeps pointing at the old path. Theme sections with a pasted image URL, custom Liquid, an email template, a blog post body, a Google Merchant Center feed row someone built by hand. Product media that references the file object follows along. A hardcoded string does not, and nobody remembers writing hardcoded strings until one breaks.

So rename before upload where you can, and rename after upload only with a quick sweep for hardcoded references. If you are renaming for search visibility rather than to clear an error, the tradeoffs are laid out in our guide on renaming Shopify image files for SEO. Short version: do it during a planned migration, not on a Friday afternoon.

Why filenames matter well beyond this error

Two reasons, and the first one is the one merchants underrate.

The filename is the matching key. When any bulk tool has to decide which product a photo belongs to, the filename is the only field the photographer’s export and your Shopify catalogue reliably share. That is exactly why we built SKU based matching the way we did: read the SKU out of the filename, find the product, attach the image. Give the tool ts-1042-navy-front.jpg and it lands correctly. Give it IMG_4021.JPG and no tool on the App Store can guess, ours included. If you want the mechanics, we wrote up matching images to products by SKU and the broader bulk product image upload workflow separately.

The filename is a small SEO signal. Google’s own image guidance asks for descriptive filenames alongside alt text, because the file path is one of the hints it uses to work out what a picture shows. front.jpg tells a crawler nothing. ts-1042-navy-front.jpg tells it a little. navy-merino-crew-neck-front.jpg tells it more, which is why some stores prefer a keyword pattern over a pure SKU pattern. Our image filename SEO guide and the wider product image SEO guide cover the balance between a name a human can read and a name a script can parse.

There is a third reason that only shows up later. Once the files are in, someone has to attach the right ones to the right variant, and a filename carrying the colour makes that assignment mechanical instead of manual. Apps that assign a separate set of images to each colour variant read the filename and the alt text as signals, so a clean name pays off twice over.

How to stop it happening on the next shoot

Prevention here is cheap, which is unusual. Four habits. Get those in place and this error never comes back, not on the next shoot and not on the one after that.

Hand your photographer a one line spec: lowercase, hyphens only, SKU first, no size words at the end, no underscores before numbers. One sentence, in the brief, once. That kills the whole problem at the source, and any working product photographer will implement it without complaint because it is easier than whatever they were doing before. If you would rather send them a worked example than a rule, the Image Filename Generator builds a pattern from the product and option values that you can paste straight into the brief.

Then: never let camera defaults through to Shopify, rename the folder before the upload rather than the file after the failure, and keep one convention across the whole catalogue instead of one per season. Three things, and the third is the one that quietly rots. Most stores we look at started with a convention.

Does any of that need an app? No, and I’d rather say so plainly than pretend otherwise. It needs a naming rule and someone who enforces it. The app earns its place at volume, where you are pushing a season of images from a Google Drive folder a photographer dropped them into and you want the failures reported rather than silent. That is a different problem from the one you came here with, and if you are not at that volume yet, the manual path above is genuinely the right answer.

One last practical note. If your uploads are failing for reasons that are not names at all, the other common wall is resolution. Shopify caps product and collection images at 20 MB and 25 megapixels (5000 by 5000 pixels), while Content, Files, theme assets and blog images cap at 20 megapixels, and the aspect ratio has to sit between 100:1 and 1:100. We covered that error separately in the 25 megapixel image limit fix, because it produces a completely different message and a completely different remedy.

Frequently asked questions

Why does Shopify say “Media could not be created because a file with the same name already exists” when I cannot find the file?

Because filenames are unique per shop, not per product, and a file uploaded directly onto a product page does not always appear in Content, Files. Search the exact name without its extension in Files, and if nothing comes back, look at the products you edited with that same shoot. The blocking file exists. It is just not in the library you are searching.

Can I overwrite a Shopify image by uploading a new version with the same name?

No. Shopify refuses the second upload rather than replacing the first, which is deliberate: overwriting a file that is already serving on a live storefront would silently change every page using it. To replace an image, delete or rename the original first, then upload. Check what references the old file before you delete it.

Which app should I use to bulk upload product images without duplicate filename errors?

CS Smart Bulk Image Upload, which we build at Craftshift. It matches each file to its product by SKU from the filename, imports straight from a Google Drive folder, uploads to many products in one pass, and keeps going with progress tracking and error recovery when an individual file is refused, so one collision does not end a 400 file batch. It is rated 5.0 stars across 97 reviews on the Shopify App Store. It does not invent names for you though: a clean naming convention is still your side of the deal.

Why can a Shopify image filename not end with large, medium or grande?

Those are Shopify’s own CDN size names. The CDN lets you request a rendered size by appending one to the file stem, so a filename ending in one of them collides with that grammar. The full reserved list is pico, icon, thumb, testing, small, compact, medium, large and grande. Filenames also cannot begin with a period, and an underscore directly before dimensions, as in product_image_5x4.jpeg, should become a hyphen.

Does renaming an image in Content, Files break my product pages?

Editing the URL Handle changes the public CDN URL, so anything holding a hardcoded copy of the old URL breaks: theme sections with a pasted image link, custom Liquid, email templates, a hand built product feed. Product media that references the file object follows the rename. Sweep for hardcoded URLs before you rename anything that has been live for a while.

What is DUPLICATE_FILENAME_ERROR in the Shopify Admin API?

It is the error code the Admin GraphQL API returns when a media or file creation call uses a filename that already exists in the shop. It appears in both the MediaErrorCode and FileErrorCode enumerations, and it maps to the admin messages “Media could not be created because a file with the same name already exists.” and “File could not be created because a file with the same name already exists.” On fileCreate the behaviour is selectable: duplicateResolutionMode set to RAISE_ERROR, the default, returns this code, while APPEND_UUID appends a unique identifier and lets the upload through. The API does not return the identifier of the conflicting file, so no app can point you at it.

Do image filenames actually affect Shopify SEO?

A little, and never as much as alt text or page content. Google’s image guidance asks for descriptive filenames because the path is one signal it uses to understand a picture. The bigger practical payoff is operational: a descriptive filename is what lets bulk tools match images to products and variants without human sorting. Treat it as a matching key first and a ranking hint second.

Related reading

• The Shopify image filename SEO guide, the naming conventions that survive a catalogue migration
• Renaming Shopify image files for SEO, when it is worth the URL churn
• The 25 megapixel image limit error, the other upload wall merchants hit
• How many images per variant Shopify allows, once the files are actually in
• Multiple images per variant on combined listings, for colour as product catalogues

Before the next shoot lands in your inbox

Fix the export, not the error. A rename pattern agreed once with whoever shoots your products retires this whole problem, the nine reserved suffixes included, and it costs one sentence in a brief. Then, when a season arrives as 1,800 files in a shared folder, the upload becomes a background job rather than an afternoon of reading rejection messages that do not say which file they mean.