Troubleshooting: CSV Import Issues

If your CSV import fails, partially imports, or creates unexpected records, check these common causes.

"Some rows failed" or partial import

Missing required column: every row must have a Name value. Blank names are skipped.
Encoding: save your CSV as UTF-8. Excel sometimes saves as ANSI or Windows-1252, which corrupts special characters (accents, non-Latin scripts). In Excel: File → Save As → choose "CSV UTF-8".
Extra commas or line breaks inside a cell: if a description field contains commas, the cell must be wrapped in double quotes. Most spreadsheet apps handle this automatically — but copy-pasted data from websites sometimes breaks the quoting.

Columns not mapping correctly

Column headers must match Shelf's expected names exactly (case-sensitive). Check the CSV import guide for the full column reference.
Custom fields: use the exact custom field name as the column header. If your custom field is called "Purchase Date", the CSV header must be Purchase Date — not purchase_date or PurchaseDate.

"Duplicate" assets created instead of updates

This happens when you use the Import flow (which creates new assets) instead of the Update Existing Assets flow (which matches by ID and updates in place).

To update existing assets: go to the Assets index → Actions → Update Existing Assets (not Import)
The update flow matches rows to existing assets by their ID column
Full walkthrough: Bulk Updating Assets via CSV

Import succeeds but data looks wrong

Date formats: Shelf expects dates as YYYY-MM-DD (e.g. 2026-04-17). Other formats (04/17/2026, 17 Apr 2026) may import as text instead of dates.
Number fields: remove currency symbols and thousands separators. 12359.00 works; $12,359.00 does not.
Boolean fields: use true / false (lowercase).

File too large

Shelf's import handles most file sizes, but very large CSVs (10,000+ rows) may time out on slower connections. If this happens:

Split the file into batches of 2,000–5,000 rows
Import each batch separately
All batches land in the same workspace

Still stuck?

Contact support with:

The CSV file (or a sample with the problematic rows)
The error message or screenshot of the import result
Whether you were using Import (new assets) or Update Existing Assets

Importing Assets to Shelf: CSV Guide — full column reference and preparation steps
Bulk Updating Assets via CSV — the update workflow (not import)