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 Assets → Import → Update existing (not the plain Import flow)
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 custom fields (cf:…,type:date): values must be in YYYY-MM-DD format (e.g. 2026-04-17). Any other format — 04/17/2026, 17-04-2026, 17 Apr 2026 — and impossible calendar dates like 2026-02-31 now stop the import with a clear error so you can fix the value, rather than being accepted. (Previously a day-first dash format such as 03-04-2026 could be silently stored as a wrong date like 1908-10-16; that no longer happens.) Reformat the column to YYYY-MM-DD and re-import.
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.

Update flow: a column didn't apply

In Update Existing Assets, an unrecognized or inapplicable column never stops the file. It is listed in the preview and skipped, so the usual symptom is that everything else updated and one column did nothing. The common causes:

The header isn't one Shelf writes. Both header styles are accepted, the Standard export's labels (Value, Asset model) and the Import-ready export's keys (valuation, assetModel), and capitalization doesn't matter. What does matter is spelling: a header that is neither is listed under unrecognized columns and ignored.
A custom field column names a field that doesn't exist here. The update flow writes to existing custom fields, it does not create them. The preview lists the field by name, so create that field under Settings → Custom fields and re-analyze.
The quantity cell still has its unit in it. A Standard export writes 10 boxes for a pooled asset. The update workflow needs 10. A cell it can't read as a whole number is flagged in the preview with a warning and skipped, while the row's other changes still apply. An Import-ready export writes a plain number, so it doesn't hit this.
The quantity columns aren't in the export. Min quantity, Unit of measure, and Consumption type are not in a Standard export. Add the columns yourself with exactly those names, or export Import-ready, which already includes them.
The asset has stock in more than one location. A Location cell can't say which placement you meant, so the location change is flagged with a warning and skipped while the rest of the row applies. Move those units from the asset's location panel.
Asset model was set on a quantity-tracked asset. Models group individually tracked assets only. The preview shows a warning on that cell, the model is not linked, and the rest of the row updates as normal.
A quantity column was set on an individually tracked asset. Those cells are ignored without a warning, since they ride along in every export.
You tried to change Tracking method. Asset type is fixed at creation, so the cell is ignored whatever it says.
A blank cell didn't clear the value. Asset model, Quantity, Min quantity, Unit of measure, and Consumption type keep their current value when the cell is empty. Clear them on the asset itself.

Full column reference: Bulk Updating Assets via CSV.

Update flow: the file is rejected before the preview

Four checks run before Shelf builds a preview, each with its own message:

No identifier column. The file needs id, ID, or Asset ID. An Import-ready export always has one, in either column scope. A Standard export only carries ID when that column is visible in your index or you pick the All columns scope.
Nothing updatable in the file. The identifier matched, but every other column is either unrecognized or one this flow never writes (Status, Kit, Custody). This usually means the wrong file. Export Import-ready and use that.
It's a workspace backup export. The backup from Workspace settings → General stores category, tags, and asset model as raw data rather than names, so it can't be matched to real entities. Export from the Asset Index instead.
Too many rows. The limit is 1,000 assets per file. Split larger files into batches.

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)