Add to Preferred Sources
Shopify CSV import errors are the single biggest time-sink when building or migrating a South African online store — the importer accepts your file, then either rejects rows silently or throws error messages that read like a foreign language. With South Africa's online retail market forecast to reach R159 billion in 2026 (World Wide Worx, Sep 2026), getting your product catalogue live quickly matters. Start with the Shopify South Africa guide if you're still deciding whether Shopify is the right platform; this post assumes you're already building and your import is broken.
This guide covers every common error, why it happens, and the exact fix — including the traps specific to operators working from local supplier spreadsheets and South African Excel installs.
Most Shopify CSV import errors trace back to four root causes: incorrect file encoding, a malformed Handle column, an invalid Variant Inventory Policy value, or an image URL that Shopify cannot reach. Fix those four and you resolve the overwhelming majority of failed imports before they reach the importer. The sections below work through each cause in order of how often it appears in the wild, plus a pre-upload checklist at the end that takes under ten minutes to run.
Quick Answer
Shopify CSV import errors are almost always caused by one of four issues: the file is not UTF-8 encoded (common when exporting from South African Excel installs), the Handle column has missing or duplicate values, the Variant Inventory Policy column contains anything other than exactly deny or continue, or an image URL is not publicly accessible. Fix the encoding first — open the file in a plain text editor, resave as UTF-8 with comma delimiters — then work through Handle, variant, and image errors in that order. Shopify's file size limit is 15 MB; split larger catalogues into separate uploads.
Jump to a section
What causes Shopify CSV import errors
File-level errors — encoding, delimiters and headers
Handle and product data errors
Variant errors — inventory policy, options and pricing
Image upload failures in CSV imports
Is your Shopify store stalled before it's live?
Send us your import file and we'll identify what's blocking it — no obligation, and we'll get back to you within 24 hours.
Get your import reviewedWhat causes Shopify CSV import errors?
Shopify CSV import errors fall into four categories: file structure problems (encoding, delimiters, headers, file size), product data problems (Handle column, Title column), variant data problems (inventory policy, option uniqueness, pricing), and image problems (inaccessible URLs, oversized files, unsupported formats). Understanding which category your Shopify CSV import problems belong to tells you where to look first — most errors give you an error message and a line number, but some drop data silently with no message at all, which is why a pre-upload checklist matters.
| Error class | Signals something is wrong | Silent or visible? |
|---|---|---|
| File structure | Full upload rejected; "We couldn't import your CSV" | Visible |
| Handle / product data | "Ignored line" messages; duplicate products created | Both |
| Variant data | Named error per line (e.g. "Inventory policy not in list") | Visible |
| Image data | Products import but images don't appear | Silent |
| Metafield data | Products import but metafield values missing | Silent |
File-level errors — encoding, delimiters and headers
Shopify CSV upload errors that reject the entire file — rather than individual rows — are almost always a UTF-8 encoding or delimiter problem, and both are disproportionately common when working from South African Excel installs or from supplier spreadsheets.
Encoding: UTF-8 is not optional
Shopify requires UTF-8 encoding. Files saved in Windows-1252 or Latin-1 (common when exporting from Microsoft Excel with South African regional settings) produce garbled characters in product titles and descriptions, or cause entire rows to be rejected. The error that gives this away is "Illegal quoting on line" — it appears when the parser hits a character it cannot interpret as UTF-8.
Fix: Open the CSV in a plain text editor (Notepad++, TextEdit, VS Code — not Excel). Use File → Save As → and select UTF-8 encoding. Then verify the delimiter is a comma, not a semicolon (see below).
SA-specific trap: Afrikaans product descriptions that include diacritical characters (ê, ë, ô) will corrupt on import if your file is not UTF-8. These characters are inside UTF-8's supported range, so UTF-8 encoding solves the problem — the fix is the same.
Delimiter: Excel may export semicolons, not commas
Microsoft Excel on some Windows locales exports CSVs using semicolons as the field separator instead of commas. Shopify expects comma-delimited files and will silently misread a semicolon-delimited file, producing a "missing required headers" error or a file that imports a single column. This affects operators who receive product data from European suppliers (the Netherlands, Germany) or who run Excel with a non-standard locale.
What it looks like: You open your "CSV" file and see all the columns merged into one long string, separated by semicolons. Or Shopify throws "Invalid CSV header: missing headers" even though you can see the headers in Excel.
Fix: Use Google Sheets instead of Excel for all Shopify CSV editing. Import your file via File → Import, choose comma as separator, edit, then export via File → Download → Comma-separated values (.csv). Upload that file directly — do not reopen in Excel before uploading.
Header errors and file size
Column header names in Shopify's CSV format are case-sensitive: Handle is not the same as handle or HANDLE. If you've built your import file manually or merged data from multiple supplier files, check every header against Shopify's sample template exactly. The "Invalid CSV header: missing headers" error always names the missing column — go directly to the header row and fix the case or spelling.
Shopify's CSV import limit is 15 MB per file. Catalogues larger than this need to be split into batches. The safest split is by product category or by supplier — this also makes it easier to troubleshoot a batch that fails without having to re-examine the entire catalogue.
Handle and product data errors
The Handle column is Shopify's internal identifier for every product — it must be unique, lowercase, contain no spaces, and use hyphens as the only separator. Handle errors are particularly dangerous because many of them produce no error message: they simply overwrite your existing live product data.
The silent overwrite problem
When a Handle in your import CSV matches a Handle that already exists in your Shopify store, Shopify treats that row as an update to the existing product — not a new product. If your data is incorrect, this overwrites live listings silently. Before importing any CSV into a live store, export your current product data first and keep it as a backup. Never import without a recovery file.
Rule: Export your current product catalogue from Shopify before every import. One accidental handle collision can overwrite dozens of live products with no error message and no undo button.
A matching Handle does not always overwrite silently. When the same Handle appears more than once within the same import file, Shopify generates a visible error: "Ignored line — handle already exists." This distinguishes the two scenarios: a Handle collision with your live store produces a silent update, while a Handle that repeats within the import file produces a named warning in the import log. If you see "Ignored line — handle already exists," remove the duplicate row — do not assume the product was imported correctly.
"Ignored line — no product data" errors
Each product row needs a Handle and a Title. Each variant row needs the same Handle as its parent product. If a variant row has a Handle that doesn't match any product row in the same import, Shopify ignores it. The "Ignored line #-## no product data" error tells you a row had a Handle but no Title — add the product title to that row, or confirm you haven't accidentally deleted a row during editing.
When you export a Shopify product that has multiple images, each image gets its own row in the CSV. If you sort or filter the export in Excel, those rows detach from their parent product rows. Shopify explicitly warns against sorting an exported CSV in a spreadsheet program for exactly this reason.
Variant errors — inventory policy, options and pricing
Variant-level errors are the most commonly searched class of problem when operators need to fix Shopify import errors — and the most fixable, because Shopify always tells you exactly which column is wrong.
The inventory policy error
"Inventory policy is not included in the list" is the most common named error in Shopify CSV imports. The Variant Inventory Policy column accepts only two values: deny (stop selling when out of stock) or continue (keep selling when out of stock). Any variation — a capital letter, a trailing space, the value "Deny selling when out of stock", a blank cell — fails the row.
Broken values: Deny, CONTINUE, deny selling, deny (trailing space), blank
Correct values: deny or continue — exactly, lowercase, no spaces, every variant row
If you are not tracking inventory for a product, leave the Variant Inventory Tracker column blank — but you still need a valid Inventory Policy value in the Policy column.
Fulfillment service errors
"Fulfillment service can't be blank" means the Variant Fulfillment Service column is empty. If you fulfil orders yourself (as most SA operators do), the value is manual. If you use a third-party service like The Courier Guy or a pick-and-pack warehouse, enter that service's name exactly as it appears in your Shopify Fulfillment Services settings.
Duplicate option values and price errors
Shopify rejects any product that has two variants with identical option combinations. If you have a clothing product with Size and Colour options, you cannot have two rows where Size = M and Colour = Black — that's a duplicate. The error is "Validation failed: options not unique." The fix is to remove the duplicate row or give one variant a distinguishing option (like a size run).
A blank Variant Price cell throws "Validation failed: price can't be blank." Every variant row must have a price, even if it's the same as the default product price. If you're building a CSV from supplier data, this is the column most likely to contain text like "POA" or "TBC" — replace those with actual numbers before importing.
Building a large SA product catalogue from scratch?
Share your product structure and we'll tell you the fastest import path — whether that's a staged CSV import or a direct Shopify integration with your supplier's system.
Get a catalogue planImage upload failures in CSV imports
Image errors in Shopify CSV imports are the hardest to catch because they're silent: your products import successfully, but the images don't appear. You only notice when you browse your catalogue and find product listings with no photo.
Why images fail silently
Shopify fetches images from the URL you provide in the CSV at import time. If that URL is not publicly accessible — it's behind a login, the file has been moved, the URL uses a signed token that has expired — Shopify skips the image without flagging an error. The product exists in your store with no image attached.
Common SA scenarios where this happens: images hosted on a supplier's internal server behind a VPN, Google Drive "share" links (which don't serve the raw image file), Dropbox preview links, or images stored on a previous ecommerce platform that has since been taken offline during a migration.
Fix: Before importing, paste each image URL into an incognito browser tab and confirm the image loads directly. The test is whether the URL resolves to the image itself — either a direct file-extension path or a CDN URL that returns the correct image Content-Type header — not a preview or share page. A parameterised CDN URL like https://cdn.example.com/img/product?id=123 will work if it serves the image directly; a Google Drive or Dropbox share URL will not, even if it looks like a file link. Use a public cloud storage bucket (AWS S3, Google Cloud Storage) to host images during import if your current hosting requires authentication.
Image size and format requirements
Shopify's product image limit is 25 megapixels — a maximum of 5,000 × 5,000 pixels. The Shopify error message reads: "Validation failed: The uploaded image exceeds the 20 megapixel limit." Note that the error cites 20 megapixels while Shopify's documentation states the ceiling as 25 megapixels; keep images under 5,000 × 5,000 px regardless of which number the error displays. Supported formats are JPEG, PNG, GIF, and WebP — TIFF and BMP are not accepted.
Pre-upload checklist for SA operators
Running this checklist before every Shopify product CSV import catches the majority of errors before they reach the importer. It takes under ten minutes on a typical product file.
| Check | How to verify | What to fix if wrong |
|---|---|---|
| UTF-8 encoding | Open in Notepad++ → Encoding menu shows "UTF-8" | File → Save As → UTF-8 |
| Comma delimiter (not semicolon) | Open in plain text editor; columns separated by commas | Export fresh from Google Sheets |
| No smart/curly quotes | Search for " or " in a text editor; should find nothing | Find/replace with straight quotes |
| File size under 15 MB | Check file properties | Split catalogue into batches by category |
| All headers match template exactly (case-sensitive) | Compare row 1 of your file to Shopify sample CSV | Fix case/spelling; never rename columns |
| Every row has a Handle | Filter for blank Handle cells | Add Handle or delete blank rows |
| No duplicate Handles (unless intentional update) | Export current Shopify products; compare Handle columns | Rename new product Handles to avoid collision |
| Inventory Policy = "deny" or "continue" everywhere | Filter Variant Inventory Policy column for anything else | Replace with exactly "deny" or "continue" |
| Fulfillment Service = "manual" or named service | Filter column for blanks | Enter "manual" for self-fulfilled products |
| No blank Variant Price cells | Filter for blanks in Variant Price column | Enter actual price (no "POA", no text) |
| All image URLs load in incognito browser | Paste 5–10 URLs to spot-check; test any that look unusual | Rehost on public CDN; update URL in CSV |
| Images under 5,000 × 5,000 px | Check image properties in file browser | Resize in Photoshop, Canva, or Squoosh |
| Backup of current store exported | Products → Export → All products (CSV) | Do not import without this |
Google Sheets, not Excel. Use Google Sheets for all CSV editing: import via File → Import, choose comma separator, edit, then export via File → Download → Comma-separated values. Upload directly from your Downloads folder without reopening in Excel. This single workflow change eliminates the encoding and delimiter errors that account for the majority of Shopify CSV import errors on SA machines.
GS1 barcode data from local suppliers: If your supplier provides a product file with GTIN or barcode numbers, Excel may convert long numeric strings to scientific notation (e.g., 6001234567890 becomes 6.00123E+12). This corrupts the barcode data. In Google Sheets, format the barcode column as Plain Text before pasting the data — or prefix each value with a single apostrophe to force text format. The apostrophe won't appear in the exported CSV.
Migrating a large catalogue from another platform?
Let us review your export file and map it to Shopify's CSV format — we handle product data cleanup, image migration and variant restructuring as part of a full Shopify build.
Book a migration assessmentWhy South African Businesses Work with Growth Pulse Media
South African operators work with Growth Pulse Media because every Shopify engagement is handled by senior staff who built and scaled a South African ecommerce operation before doing this professionally — the supplier CSV import workflows, SA payment gateway configurations, and POPIA-compliant checkout decisions you're working through now are territory Dirk van Greuning and the team have covered first-hand. Growth Pulse Media is a registered Shopify Partner and Shopify marketing agency — not a generic web studio that lists Shopify as a capability, and not a firm that routes your build through junior staff.
We work with a limited number of clients at any one time, which means your Shopify store build gets the same attention as our largest accounts. We integrate with PayFast, Peach Payments, Ozow, and Yoco; we set up GA4 ecommerce tracking, Klaviyo or Omnisend email flows, and The Courier Guy or Aramex fulfilment — all in-house, with SA tax and POPIA compliance built in. If your CSV import is a symptom of a larger cataloguing problem, we'll diagnose the root cause rather than fix the surface error and leave the structure broken.
See our ecommerce build project plan for how a full Shopify launch is structured end-to-end, and our guide on Shopify product bundles if your catalogue includes bundled SKUs that need special variant handling.
Who This Import Fix Guide Is NOT For
Stores with fewer than 20 products. If your catalogue is small, entering products manually in the Shopify admin is faster and less error-prone than building and debugging a CSV. The importer is built for bulk operations — use it when it saves time, not as the default entry point.
Operators who want an app to handle this automatically. Several Shopify apps promise to "fix" CSV import issues by pre-processing your file. They work, but they add a dependency and a monthly cost for something that a one-time encoding fix and a Google Sheets workflow solve permanently. If you need the same import every week (e.g., weekly stock updates from a distributor), an app or API integration is the right answer — but not as a workaround for a one-off structural problem.
Businesses expecting Shopify to recover a corrupted file. Shopify's own documentation states it cannot recover corrupted CSV files. If you save a CSV from Shopify in Excel without confirming UTF-8 encoding, then re-upload it, the corrupted data is what Shopify stores. Always work from the original export or a Google Sheets copy — never from an Excel-resaved version of a Shopify export.
Stores using variant metafields via CSV. Variant-level metafield values are silently ignored during CSV import — Shopify's importer doesn't process them. If you need variant metafield data (for example, a per-size fit guide or per-colour material spec), you need to add those values via Shopify's bulk metafield editor or the API after the base import is complete.
Frequently Asked Questions from SA Store Owners
Why does my Shopify CSV import succeed but no images appear?
Image failures during Shopify CSV import are silent — the importer doesn't flag them. The most common cause is an image URL that Shopify can't access publicly at import time: a broken link, an expired signed URL, a Google Drive preview link, or an image on a server that requires login. Test every image URL in an incognito browser tab before importing; if the image doesn't load there, Shopify won't fetch it either.
What exactly does "Variant Inventory Policy is not included in the list" mean?
It means the Variant Inventory Policy column in your CSV contains a value other than the two accepted options: deny or continue. Shopify is case-sensitive here — Deny with a capital D will fail. Check every row in the column for capital letters, trailing spaces, blank cells, or descriptive text like "deny selling when out of stock." Replace all values with exactly deny or continue in lowercase.
Can I use Excel to edit a Shopify CSV export?
You can, but it's risky. Excel on some Windows locales saves files with semicolons instead of commas, and it can also re-save a UTF-8 file with Windows-1252 encoding if you don't manually select UTF-8 on save. Sorting an exported file in Excel also breaks image URL associations. The safer workflow is to import into Google Sheets, edit there, and export directly back to CSV without opening in Excel at all.
Why did my import overwrite existing products instead of adding new ones?
When a Handle in your CSV matches a Handle that already exists in your Shopify store, Shopify treats that row as an update and overwrites the existing product data without flagging an error — that is the silent overwrite. If the same Handle appears more than once within your import file itself, Shopify generates a visible warning in the import log: "Ignored line — handle already exists." Always export your current catalogue before importing and compare Handle columns between your new file and the export to identify live-store collisions before they cause silent overwrites.
My CSV is under 15 MB but still won't upload — what else could block it?
File size is just one limit. Other causes of a complete upload failure include: the file is not saved as a true CSV (some tools save as .xlsx with a .csv extension), the file uses semicolons as delimiters rather than commas, the file contains a BOM (byte order mark) character at the start that some text editors add, or the first row is not the header row (a common issue when the file came from a supplier who added a company name or date in row 1). Open the file in a plain text editor and confirm row 1 is the column header row and that fields are comma-separated.
Fix Your Shopify Import — Get It Right First Time
Growth Pulse Media is a registered Shopify Partner based in Johannesburg. We handle product catalogue imports, variant structure, SA payment gateway setup (PayFast, Peach Payments, Ozow), and ecommerce email flows via Klaviyo and Omnisend — all in-house, with senior attention on every account. No obligation — we'll get back to you within 24 hours.
Talk to us about your Shopify store