Which cause is yours?
| What you observe | Most likely cause |
|---|---|
| Column mapping screen shows only 1 column with semicolon-separated text | 1. Semicolon delimiter (regional Excel setting) |
| Special characters, umlauts (ä, ö, ü) or accents (é, à) turn into garbled text | 2. Encoding: not UTF-8, or converted twice |
| First column header (e.g. ID or Type) fails to match or shows an unknown character | 3. UTF-8 Byte Order Mark (BOM) signature |
| Descriptions spill across multiple rows; prices shift into wrong columns | 4. Unescaped quotation marks in descriptions |
1. CSV is crammed into one column: semicolon vs comma delimiter
In many regions (Germany, France, Italy, Spain, Poland, Ukraine and others) Excel writes CSV files with a semicolon (;) because the comma is the decimal separator there. The WooCommerce importer expects a comma unless you tell it otherwise, so it sees each whole line as one field.
| Record | Type | SKU | Name | Regular price |
|---|---|---|---|---|
| 1 | simple | MUG-01 | Mug | 12.50 |
| 2 | simple | MUG-02 | Mug; large | 14.00 |
Record numbers exclude the header. (empty) marks an empty cell; · marks outer spaces and ↵ a line break.
Fix in WooCommerce:
- On the first screen of the importer (Products → Import), open Show advanced options.
- In the CSV Delimiter field, replace the comma with a semicolon (
;). - Continue: the mapping screen now shows every column separately.
CatalogDock detects a comma or a semicolon in the header line and switches to it before the check; if you choose the wrong one, it refuses the file with an explanation instead of guessing the columns.
Fixed automatically
Nothing is re-encoded or re-delimited: a corrected CSV keeps the delimiter and line endings of your file. Its BOM follows the copy you download (see section 3).
Reported for you to decide
- A file that is not valid UTF-8, with the position of the first invalid byte; save it as UTF-8 and check again.
- A delimiter that does not match the file (
CSV_WRONG_DELIMITER) and broken quoting (CSV_MALFORMED).
2. Broken characters and mojibake: UTF-8 vs ANSI encoding
WooCommerce expects UTF-8. Garbled text has more than one cause, and the pattern you see tells them apart:
- The file was saved in a legacy code page (for example with Excel's plain "CSV (Comma delimited)" on Windows, which uses Windows-1252 or Windows-1251 depending on the system). Read as UTF-8, its accented letters are invalid bytes and usually show as
�or vanish:cafébecomescaf�. - UTF-8 text was read as a legacy code page and saved again (for example opened in a spreadsheet with the wrong encoding, then saved). Each accented letter turns into two or three characters:
cafébecomescafé,GrößebecomesGröße. The file is now valid UTF-8 containing the wrong text.
Fix: go back to the original workbook or export and save it again as CSV UTF-8 (Comma delimited) (*.csv) in Excel, or as UTF-8 in LibreOffice. Do not "repair" already garbled text by search and replace: you would have to know every substitution.
What CatalogDock does: it refuses a file that is not valid UTF-8 (also UTF-16) and names the first invalid byte. It does not convert encodings and cannot repair text that is already garbled inside a valid UTF-8 file (café is valid UTF-8): check a few names in the preview.
3. Byte order mark (BOM) in UTF-8 files
Excel's "CSV UTF-8" adds a 3-byte signature, the Byte Order Mark (EF BB BF), at the start of the file. The built-in WooCommerce importer reads such a file correctly. Some other tools do not, and then the first header looks like Type instead of Type.
What CatalogDock does: it reads files with and without a BOM. The corrected web CSV is available as UTF-8 without a BOM, with a separate UTF-8 BOM copy for Excel, so you can choose. An unchanged-original download may retain the original bytes, BOM included. To remove a BOM yourself, save the file as "UTF-8" (not "UTF-8 with BOM") in an editor such as VS Code or Notepad++.
4. Columns shifting: Quotes and newlines in HTML descriptions
Descriptions often contain line breaks, commas and quotation marks (such as 24" for inches). In a CSV file a field with a comma, a line break or a quote must be enclosed in double quotes, and a quote inside it is written twice ("").
This file is deliberately malformed. The table identifies the quote error; it does not assume a split into column values. Download or copy the original file to reproduce the error.
| Record | Field | Parsing problem |
|---|---|---|
| 1 | Description | The quote after 24 is not doubled. The following column boundaries cannot be parsed reliably. |
Record numbers exclude the header. (empty) marks an empty cell; · marks outer spaces and ↵ a line break.
| Record | Type | SKU | Name | Description | Regular price |
|---|---|---|---|---|---|
| 1 | simple | MON-01 | Monitor | High quality 24" display, 4K | 299.00 |
| 2 | simple | MON-02 | Monitor 27 | Two lines:↵stand included | 349.00 |
Record numbers exclude the header. (empty) marks an empty cell; · marks outer spaces and ↵ a line break.
Fix: export the file from a spreadsheet application (Excel, LibreOffice, Google Sheets), which quotes fields correctly, instead of building CSV lines by hand; or check the Excel workbook itself in CatalogDock, where cell boundaries are explicit.
Still failing?
- Server timeouts during import: If the file reads correctly but the server stops with a 504 error, see WooCommerce import 504 timeout & safe batches.
- Variations not appearing: See WooCommerce variations not linking or showing.
- Duplicate SKU errors: See "Invalid or duplicated SKU" causes & fixes.
Check your delimiter and encoding automatically
Drop your CSV or Excel file into CatalogDock. The free in-browser checker detects comma or semicolon, refuses a file that is not valid UTF-8 (and says where the first invalid byte is), and previews your columns before you import.
Runs in your browser · No files uploaded · Never connects to your store
Applies to the built-in WooCommerce CSV importer (Products → Import); importer behavior as in WooCommerce 11.1.2 (on WordPress 7.1.2). The CSV examples are complete files you can copy or download. Each gives the result stated next to it in the CatalogDock checker (an automated file check, not an import).