Shopify CSV Import Errors: What Each One Means and the Fix

Shopify answered your upload with one line: Ignored line … because handle … already exists, or Invalid CSV header: missing headers. Or the import went through, and now the descriptions are full of strange characters, the images never arrived, or the variants you had are gone. Or a Choose column headings window opened instead of an import.

Each of those has a documented cause in Shopify's Help Center, and most are fixed in the file itself: one column, one cell, or the way the file was saved. This guide puts every message Shopify's troubleshooting pages list next to its cause and fix, and marks the cases where the right move is a different tool rather than another edit.

Find Your Error: From Message to Fix

Shopify's page of solutions to common product CSV import problems lists 18 error messages, as of October 2026, and its import page documents two more: Network error: Unexpected token < in JSON at position 0 and Line is invalid (No details). Match the first words of your message to a row, then jump to that section.

Where Shopify Checks the File, and What It Can't Undo

A product import runs from the Products page of your admin, in seven steps:

1. From your Shopify admin, go to Products.
2. Click Import.
3. Click Add file, and then select the CSV file you want to import.
4. Optional: deselect Publish new products to all sales channels if new products should go only to your online store.
5. Optional: select Overwrite products with matching handles if the file should replace existing values for the columns it includes.
6. Click Upload and continue.
7. Review the details about the import, and then click Import products.

If Shopify shows an error after you upload the file in step 6, fix the file and upload it again. Once the file goes through, you receive a confirmation email from Shopify. Shopify's own tip for avoiding upload issues is to use the Google Chrome browser.

Step 7 is the point of no return. In the words of Shopify's import page:

So export your products before you import anything. Shopify's caution on the same page is to make sure you have a backup of your product data before you start; the section on wrong results shows where to review recent changes an import made.

For the backup itself, use Shopify's product export, which Shopify lists as a way of creating a backup of your products. In Products, click Export, choose All products and a CSV type, then click Export products; an export of all products arrives by email.

In Shopify adminOpen in your store

1. Products
2. Export

Zoom

Shopify Academy's two-minute walk-through below shows the same flow, from preparing the file to finishing the import. It was published in June 2023, and the template has changed since: Shopify added multiple barcodes per variant in September 2026, carried in a Variant Barcodes column. Take column names from the current template, not from the video.

The two options in the import dialog

Publish new products to all sales channels is optional to change: deselect it when new products should be published only to your online store instead of to every sales channel.

Overwrite products with matching handles decides what happens to products already in your store. Without it, products in the file that match an existing handle are ignored. With it, the values in the file overwrite the existing values in the matching columns, which is what makes blank cells risky; the wrong-results table below shows how.

File, Encoding and Quote Errors

Every CSV file you give Shopify must use UTF-8 encoding, and a product file should be saved with LF-style line breaks. Editing in another program is where those properties get lost: Shopify notes that special characters don't always survive a file that was exported, edited in another spreadsheet program and imported again, and that Excel and similar programs can add curly quotes.

The encoding step counts at the moment you save, before the file ever reaches Shopify:

Google Sheets saves files with UTF-8 encoding by default; other spreadsheet software might require an extra step. If you edit in something else, choose UTF-8 explicitly every time you save.

Excel traps: leading zeros, long numbers and the save format

Four behaviors, each documented by Microsoft, are worth checking before you save a product file from Excel:

• Leading zeros and large numbers. Excel automatically removes leading zeros and converts large numbers to scientific notation, like 1.23E+15.
• Digits past the 15th. Excel has a maximum precision of 15 significant digits, so in any number with 16 or more digits, the digits past the 15th are rounded down to zero.
• Formatting afterwards. Switching a column to Text format doesn't change numbers that were already entered; it only affects numbers entered after the format is applied.
• Saving. Saving as a CSV file isn't currently possible in Excel for the web, and in desktop Excel Shopify asks you to check the export settings so the file uses commas between values.

Barcodes are long numeric codes, so they are the column to check after any Excel save. For which codes your products need and where they come from, see our Shopify barcodes guide.

Files over 15 MB

A product CSV can't exceed 15 MB, and the inventory CSV has the same ceiling. If you get an error after trying to upload a new file, or the upload times out, Shopify's fix is to split the CSV into several smaller files and upload each one; our advice is to keep every row of one handle in the same file, so no product is split across two imports.

Header and Column Errors

The first line of a product CSV must be the column headers from the product CSV column table, separated by commas, and header names are case-sensitive. If a file from another store or source doesn't match the format, or any headers are missing, the import fails.

The current sample file starts with Title and URL handle. If the first row of yours starts with Handle, you are holding a file built on the older template, which the next table translates.

Old column names on the troubleshooting page and in older files

Shopify's troubleshooting page still prints the old first row, from Handle, Title, Body (HTML) through Variant Inventory Policy and Image Src to Image Alt Text, and its fix for Inventory quantity can't be blank names the old Variant Inventory Tracker column. Shopify maintains backward compatibility with older column names, but suggests moving to the current format to ensure future compatibility.

Handle, Row and Variant Errors

A product CSV describes one product across several rows. The first row of a product carries all its fields; each following variant row repeats the URL handle and skips the Title, Description, Vendor and Tags columns.

To import new products, the required column is Title, plus URL handle if you're adding variants; to update products, the only required columns are URL handle and Title.

A product can have up to 3 options, carried in the Option1 to Option3 name and value columns, and for a product with only one option Shopify's column table says the value should be Default Title.

Updating variants on products you already have carries its own risk of losing them, so it has its own walk-through: our guide to importing variants by CSV without losing data.

Line is invalid (No details): an option moved to another position

Variant options must be unique, and Shopify checks for duplicate option names before it imports new values. A file that moves Size from Option 1 to Option 2 and adds Type as the new Option 1 therefore fails. Shopify's workaround:

1. In your CSV file, use a temporary name for the option causing the conflict, such as Size. with a period instead of Size.
2. Import the file with the temporary option name.
3. After that import completes, create a new CSV file that changes the temporary name to the name you want.
4. Import the updated file to apply the final option name.

The daily variant limit on very large catalogs

For stores with 500,000 or more product variants (excluding Plus stores), no more than 10,000 new variants can be created by CSV uploads (or API) within a 24 hour timeframe, and the timer starts at the first upload of the day. Plan a large variant import across several days; how this cap fits beside Shopify's other catalog limits is covered in how many products you can have on Shopify.

Inventory and Fulfillment Errors

Some product CSV columns only work as a set, and a file with values in only some related columns results in an import error. Shopify's own example, in a note on its page about product CSV columns, is the tracker: when Inventory tracker is set to shopify, the Continue selling when out of stock and Fulfillment service columns can't be left blank.

That note then says that if they are blank, the default values in the column table apply, while the troubleshooting page lists Fulfillment service can't be blank as an error. The two pages disagree here, as they do on a blank price below: fill Inventory quantity, Continue selling when out of stock and Fulfillment service with valid values on every tracked row, which satisfies both pages on these three columns.

The policy message has its own answer page, with what deny and continue each do and why the setting doesn't apply to point-of-sale orders.

Stock at more than one location: the inventory CSV

Inventory quantity in a product CSV is the number of items you have in stock, and it applies only to Shopify stores that have a single location. If you use multiple locations and want to import or export quantities, Shopify's instruction is to use the inventory CSV file, a separate file with its own 15 MB ceiling.

The inventory CSV has its own safeguard. When the file includes both On hand (current) and On hand (new) columns, rows whose inventory changed after your export don't import, and you receive an email with details about the failed rows. Shopify added the On hand (new) column and renamed On hand to On hand (current) in August 2025, and warned that automated tools, scripts or external systems using the inventory CSV need updating before they use the feature.

Price, Category, Status and Metafield Errors

Three messages on Shopify's troubleshooting page concern price, category and metafield values:

• Validation failed: price can't be blank. A line has no price; add the price to that line.
• Not a valid product category. The category doesn't match Shopify's Standard Product Taxonomy; enter the full category breadcrumb or the category ID, exactly as the taxonomy lists it.
• Validation failed: Value must be a valid product reference. A metafield points at a product that isn't in your store yet; import in two stages.

Shopify's own pages disagree on a blank price. The troubleshooting page lists price can't be blank as a validation failure, while the column table on the CSV page says the default value is 0.00 when no price is entered (both read October 18, 2026). Don't test which rule your file hits: put a price on every variant row, which passes under both pages.

What each value column accepts

Beyond the named messages, these columns decide whether a row imports and how the product comes out:

Metafield references: import in two stages

Product references in metafields must point to a product that already exists, so a file that creates products and references them in the same pass fails with Value must be a valid product reference. Shopify's fix is to import in stages:

1. Import your products without the metafield values.
2. Add the metafield values back to your CSV file, and import it again with Overwrite products with matching handles selected.

Variant metafields aren't supported for product CSV import or export at all; to edit them in bulk, Shopify points you to the variant bulk editor with metafield columns added. Which other custom data travels in a product CSV is covered in our metafields guide, under what actually exports.

Image Errors

A CSV holds only text, so every image arrives as a URL: Shopify downloads the image during the import and re-uploads it to your store. Each image message below is about that URL or the file behind it.

The size message has the same kind of gap. Its heading names a 20 megapixel limit, while the fix text under it, like Shopify's product media page, allows images of any size up to 5000 x 5000 px, or 25 megapixels. Keep images under 20 megapixels and a file passes under either number.

• One row per image. A product takes up to 250 images, each on its own row with the product's handle repeated.
• Final file names. Shopify downloads and re-uploads each image, and you can't edit a file name after the image is uploaded.
• No video or 3D. 3D models and videos aren't supported in the CSV; upload them in Content > Files instead.
• No sorting. Sorting the file in Excel or Apple Numbers can remove products from their image links, and those images are lost.

Images that sit only on your computer need a public URL before they can go into the file: upload them to your store in Content > Files, or to another image host, and copy each URL into the image column.

In Shopify adminOpen in your store

1. Content
2. Files

Zoom

The Import Worked, but the Products Are Wrong

These results raise no error, because the file was valid. It simply told Shopify something you didn't mean:

The overwrite rules have more edges than one table row, including dependent columns and what a CSV can't delete. They are covered in full in does importing a product CSV overwrite existing products.

To review recent changes made by an import, open the store activity log in your admin settings. It is view-only, can't be exported and displays at most 250 results, and the list goes back only as far as that maximum, so check it soon after a large import.

In Shopify adminOpen in your store

1. Settings
2. General
3. Store activity log

Zoom

Pre-Import Checklist for a Product CSV

The steps follow the file from how it is saved to the dialog you upload it in. Run them again after every round of fixes, since a re-save in a spreadsheet program can undo step two.

When to Change the Approach Instead of the File

Some errors keep coming back because the product CSV is the wrong tool for the job. These are the cases where Shopify's own pages point somewhere else:

If the CSV is one piece of a full platform move, our Shopify migration guide compares the routes, from the free app and a CSV import to paid migration services, and what each one moves.

The Bottom Line

The table at the top of this page sends each message to its fix, and the table in the previous section sends each job that isn't a product file to its tool.

Frequently Asked Questions