CSV column headers that don't match the template

Your store import rejects a product CSV when the header row does not match the import template. The importer reads the first row as column names. If a name differs from what the template expects, that column is not recognised, and the whole file can be refused.

The symptom. You upload the file and see an error about missing or unknown columns, or the import finishes with some fields empty. Often the file looks perfectly normal when you open it, because a small difference in a header is easy to miss by eye.

Find it by hand. Open the template and your file side by side, and go through the headers one at a time. Compare each header with the template header in the same position, character by character. Look for spelling differences, such as a missing letter or a swapped pair of letters. Look for spaces at the start or end of a header, or two spaces in the middle; they are invisible but count as different text. Compare capital letters and punctuation, including underscores and hyphens. If the template lists columns in a set order, note every column that sits in a different place. List every template column missing from your file, and every extra column the template does not have.

Fix it. Change only the header row and leave the product rows alone. Rename each header so it matches the template exactly. Delete stray spaces from the start and end. Rewrite wrong spelling and capitals by copying the header from the template rather than typing it again. Move columns into the template order. Add any missing column with the correct header, even if the cells below stay empty for now. Remove extra columns that the template does not list, after saving a copy of the original file. Save the file as CSV again and keep the same text encoding.

Check again. Compare the header row with the template once more, this time from the last column back to the first, so you read it in a fresh order. Count the columns in both and confirm the numbers match. Make sure no product row lost or gained a value when you moved columns. Then check by hand that each value still sits under the right header, using a few rows from the top, middle and end of the file. Upload again only when every header matches.

The free CSV check reads the header row too: if it cannot find a SKU, title or price column under a common name, it reports a missing column. It ignores capital letters and spaces at the edges of header names, so still compare those with your template by hand.

If image links in the same file also fail, read our post "Broken image links in a product CSV: find and fix".