Skip to content
Get started
Browse the documentation

Mapping errors and common mapping mistakes

Every message the editor shows when you save a mapping and every message a row can get for a field, with the fix, plus the mistakes behind most surprises.

  • 5 min read
  • Updated October 13, 2026
On this page

Mapping is checked in two places. When you save, the editor checks the mapping (the choices you made) against the sample's columns and the site's fields, and shows what is wrong under the field. When a file is read, every row is resolved with the mapping and the row is checked, and a problem becomes a row error in the review (row errors).

Messages when you save#

Message What it means and what to do
Choose a value for this required destination field. A required field (the title; on Joomla also the category) has no source. Choose a column, a fixed value or a template.
Every item needs a Category. Set it from a column or a fixed value. Joomla: the category has no source.
Choose how this field should get its value. The field's mode list is empty. Choose one.
Choose an available source column. The column you chose is not in the sample file. Choose another, or upload a sample that has it.
This field cannot be emptied. Choose where its value comes from. Remove from every item is only for free-text fields that are not required.
The site doesn't offer this field, for example because the account Content Uploader publishes as may not set it. Remove it from the configuration, or allow it on the site and refresh the site's fields. A mapped field disappeared from the site (a plugin was removed, a permission was taken away). Remove the field from the mapping, or restore it and select Refresh fields on the Sites page.
Enter a template for this required field. / Enter a template no longer than 262,144 characters. A template is empty or too long.
Choose whether to replace, remove or preserve existing terms. The category or tag box has no mode.
The hierarchy separator must be one character. / The value separator must be one character. The separators are single characters.
Choose an available parent column. The Parent category column is not in the file.
The account Content Uploader publishes as on this site may not add new terms in this taxonomy. Untick Add new … to the site when they don't exist yet, or allow the account to create terms.
This taxonomy is not assignable for the selected destination type. / This image is not available for the selected destination type. Something mapped for one content type was kept after you changed the type. Remove it.
Enter an image address or file name. / The destination does not accept this for images. An image fixed value is empty, or alt text, title or caption is not accepted for that slot.
Choose a value for this required custom field. A required custom field has no source.
The site doesn't offer this custom field … A custom field was removed or the account may not edit it.
Enter a name for this custom field. / Custom field names cannot start or end with a space. / …cannot contain line breaks. / Use a custom field name that is not only a number. The name you typed for a new custom field is not valid.
Select a writable destination content type. / This content type is not writable through the connected site. The content type cannot be written. Choose another.

Messages for a row#

A row error is shown with the field's name first (Title: …, Publish date: …).

Message Meaning
This field resolves to an empty value. A required field is empty in this row.
The resolved value must be a valid date. The date cell is not a date (dates).
The resolved value must be a whole number. / …a number, such as 12 or 12.5. / …yes or no, such as TRUE, FALSE, 1 or 0. The value does not fit the field's type.
The resolved value is not one of the destination choices. A choice such as Status is not one the site offers.
This value matches more than one destination choice. Use the choice's key instead. / …Use its numeric ID instead. Two choices fit; use the key or the ID.
No destination choice matches this ID. Refresh the site fields or correct the value. An author's number that the site does not list.
No destination choice matches this value. Use the exact display name, email address, username or numeric ID, or refresh the site fields. A name, email address or user name that the site does not list (or a user who cannot write content).
The resolved value exceeds the N character limit. The text is longer than the field allows.
The template refers to an unavailable column: X. A placeholder names a column that is not in the file.
This row has 2 values for Category (A, B), but an item can have only one. Joomla: several categories in one row.
This row has no Category. Every item needs one. Joomla: no category in this row.
Record ID: … The ID is empty, too long or repeated (duplicate rows).
This row has more cells than the header. A row of a CSV file has more values than the header row has columns.

The mistakes behind most surprises#

  1. Path columns without "Parse paths". Destinations > Malta becomes one category with that whole name. Tick Parse paths such as Parent > Child (categories).
  2. The wrong separator for tags. anchoring; malta read with Comma gives one tag named anchoring; malta. Set Values separated by to match the cells (tags).
  3. HTML in a column inserted through a placeholder. In an HTML template a placeholder inserts text, so the tags show on the page. Map the column directly (templates).
  4. A fixed Status on a site where editors publish by hand. The next file sets the status back. Choose Keep existing on updates (status).
  5. Dates written as 01/02/2026. That is 2 January, not 1 February (dates).
  6. A record ID that repeats, or changes. Repeated IDs are rejected; changed IDs make new items (choosing the record ID).
  7. An image column but no ZIP. The review lists every image as not found (where images come from).
  8. Mapping a column that disappears next week. The file is then not processed (when the columns change).
  9. Leaving "Remove from every item" on. It empties that field on every item the file publishes; the review lists them first.
  10. Not looking at the preview. Try the first, the last and the oddest row.

Was this article helpful?

Related articles