Shopify 'Invalid CSV header: missing headers': what to check and how to fix it

You choose a file, click upload and Shopify answers "Invalid CSV header: missing headers", often followed by a column name. The file never reaches the product checks. The problem is on line one, and it is usually small. The rest of the errors are in the Shopify CSV import errors guide.

What it means

The first line of a Shopify product CSV must contain the column headings Shopify recognises. If it cannot find one it requires, or cannot split the line into separate columns at all, it stops. Shopify's help page says the first line has to match its required header row and tells you to check that line for trailing spaces.

Causes

• A renamed header. Body HTML instead of Body (HTML), or Price instead of Variant Price.
• A deleted column that the importer requires.
• A trailing space after the last header, or a space inside a name.
• A blank line or a title row above the headers, common in supplier exports.
• The wrong delimiter. Semicolon or tab separated files look like one giant column.
• A byte order mark or odd encoding that attaches hidden characters to the first header.
• Mixed header styles from an old export and a newer template.

Broken and fixed

Broken, with a renamed column and a trailing space:

Handle,Title,Body HTML,Vendor,Variant Price 
linen-shirt,Linen Shirt,<p>Washed linen</p>,Northwind,49.00

Fixed:

Handle,Title,Body (HTML),Vendor,Variant Price
linen-shirt,Linen Shirt,<p>Washed linen</p>,Northwind,49.00

Shopify's required first line, as given in its help documentation, starts like this and continues through Image Src and Image Alt Text:

Handle,Title,Body (HTML),Vendor,Type,Tags,Published,Option1 Name,Option1 Value

Use the full line from the sample CSV on the import screen rather than typing it.

Step-by-step fix

1. Download the sample CSV from the Shopify import screen.
2. Open both files in a text editor, not a spreadsheet.
3. Compare line one of your file with the sample, character by character.
4. Delete any lines above the header row.
5. Remove trailing spaces and check that commas, not semicolons, separate the columns.
6. Save as UTF-8. If the first header looks odd in the editor, remove the byte order mark.
7. If your layout is very different, paste your data into the sample file under its headers.
8. Upload again. If the importer shows the column heading window, map each column carefully.

Prevention

Treat Shopify's sample as the single template and never edit its header row. Keep one master file with those headers and copy supplier data into it. Export from Google Sheets. If you need extra columns for your own use, keep them in a separate working sheet and delete them before export.

When to do it yourself and when to hand it off

Fixing line one is quick, and most store owners can manage. It becomes a time sink when supplier files arrive in different layouts every week and each needs mapping to Shopify's columns. That mapping is a regular part of our bulk product upload work, with a person reviewing every output and your approval before upload. If you want to see it on your own files, try the free 10-product sample if your project is a fit.