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 title: every row needs a title value. The importer does not reject blank titles — those rows still create asset records, just with no name, which you'd then have to clean up by hand. Validate that every row's title column is populated before uploading.
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). Unknown headers abort the entire import with "Invalid header provided." Check the CSV import guide for the full column reference.
Custom fields: headers must use the form cf:FieldName,type:TypeName — for example cf:Purchase Date,type:date. A bare Purchase Date header is not valid and will be rejected as an unknown header. In a comma-delimited file, the whole header must be wrapped in double quotes because it contains a comma: "cf:Purchase Date,type:date". In a semicolon-delimited file no quoting is needed.

"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: custom-field booleans accept only yes or no (case-insensitive). true, false, 1, 0 are silently skipped — the value will not be saved. For the bookable column, only the exact string no makes an asset non-bookable — false, blank, and yes all leave it bookable.

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)