# Troubleshoot imports

Source: https://kirora.io/docs/guides/contacts/troubleshoot-imports

Fix a CSV that won't upload, an import that stops, and rows that fail, with each message and what to do.

An import problem shows its cause where it happens: on the import page before you start, on the import's own page if the whole import stops, or next to each row that fails. Find the message below, fix the file, and import it again. Rows that match existing contacts update them rather than creating duplicates.

For the steps of an import, see [Import contacts](https://kirora.io/docs/guides/contacts/import-contacts).

## Where to find failed rows

When an import finishes, **Failed** counts the rows that weren't imported, and the table below lists each one by **Row** with its **Problem**. Row numbers count the header as row 1, so they match the line numbers in your spreadsheet (blank lines aren't counted).

- **Admins and the owner** get a page for each import. Choose **Download failed rows** for a CSV of every failed row and its problem, fix those rows and import them again. Past imports are under **Recent imports** on the import page.
- **Members** see the result, with each failed row, on the import page as soon as the import finishes.

**Skipped** rows aren't errors. They're rows that **Contacts already here** told Kirora to leave: rows matching an existing contact with **Only add new contacts**, or rows matching nobody with **Only update existing contacts**.

## The file won't upload

| Message | What to do |
| --- | --- |
| *Choose a CSV file. Other files can't be imported.* | Save the spreadsheet as CSV. In Excel, use Save As and choose CSV UTF-8. |
| *Add one CSV file at a time.* | Drop or choose a single file. |
| *This file is over 900 KB. Ask an admin to import it: they can import files up to 100 MB.* | Members can import up to 900 KB or 5,000 rows at a time. Split the file, or ask an admin or the owner. |
| *This CSV has 6,200 rows, over the 5,000 one import can take.* | Split it into files of up to 5,000 rows, or ask an admin or the owner: they can import files up to 100 MB. |
| *This file is over 100 MB. Split it into smaller files.* | Split the file. Each file can be up to 100 MB. |
| *This file isn't saved as UTF-8, so accented letters would import wrongly.* | In Excel, save it as CSV UTF-8 and choose it again. Otherwise names such as *José* would arrive garbled. |
| *The file could not be read. Try choosing it again.* | Choose the file again. If it still fails, open it in a spreadsheet and save a new copy as CSV. |

## The CSV can't be read

These show under the file or the pasted CSV before you map columns. They usually mean the file isn't plain CSV, or a quote is out of place.

| Message | What to do |
| --- | --- |
| *Add a CSV with a header row and at least one contact.* | Put column names in the first row and at least one person below. |
| *Every column needs a non-empty header.* | Give every column a name in the first row, or delete empty columns. |
| *Use unique column headers so each mapping is unambiguous.* | Rename repeated columns, for example two called `phone`. |
| *Close the quoted field before continuing.* | A value opens a quote (`"`) and never closes it. Add the closing quote. |
| *A quoted field must be followed by a comma or a new line.* | Text follows a closing quote, as in `"Lisbon" Portugal`. Put the whole value inside the quotes. |
| *Quote the entire field and escape quotes by doubling them.* | A quote sits in the middle of a value. Write `"She said ""hi"""` rather than `She said "hi"`. |

Spreadsheet apps write correct CSV for you, so saving again from a spreadsheet usually fixes these.

## You can't continue from mapping

| Message | What to do |
| --- | --- |
| *Map email, phone, or external ID before importing.* | Map at least one column to **Email**, **Phone** or **External ID**, so Kirora can tell people apart. |
| *Map at most 50 attribute columns.* | Set the columns you don't need to **Don't import**. |
| *Two columns are mapped to the attribute "plan". Give each its own name.* | Give each attribute column a different name. |
| *Name the attribute for "Loyalty tier" with letters and numbers in any language, dots, - or _ (up to 64).* | Rename the attribute, for example `loyalty_tier`. |
| *Enter what separates the items in "diet", such as ;.* | For a **Multiple values** attribute, or a **Lists** column, enter the character between items, such as `;`. |
| *Choose how they agreed.* or *Say where and how they agreed.* | You're importing consent, so say how these people agreed. See [Record consent](https://kirora.io/docs/guides/contacts/import-contacts#record-consent). |

## The whole import stopped

An admin's import runs in the background. If it can't finish, its page shows **Failed** with the reason. Rows imported before it stopped are saved, and importing the file again updates those contacts rather than duplicating them.

| Message | What to do |
| --- | --- |
| *The file is not valid CSV: …* | The rest of the message names the line. Fix it, or save the file again from a spreadsheet as CSV UTF-8. |
| *The file has more than 1000000 rows; rows up to that point were imported* | One import takes up to a million rows. Import the remaining rows as a second file. |

A member's import that can't be read shows *The CSV could not be read: …* instead, with the reason.

## Rows that failed

Each failed row's **Problem** says why. The other rows are still imported.

### Identifying the person

| Problem | What to do |
| --- | --- |
| *At least one of externalId, email, or phone is required* | The row has no email, phone or external ID in the mapped columns. Fill one in, or remove the row. |
| *Invalid email* | The address isn't written correctly, for example a missing `@` or a space. Correct it. |
| *The email belongs to a contact with a different externalId; correct the externalId, or leave it out to update that contact* | The row's email matches a contact whose external ID differs from the row's. Correct the external ID, or leave that cell blank to update the contact the email matched. The same applies with phone. |
| *A contact with this email already exists in this workspace* | The row matched one contact, but its email (or phone or external ID) belongs to another. Check which contact the row is meant for. To combine two contacts that are the same person, [merge them](https://kirora.io/docs/guides/contacts/manage-contacts#merge-a-duplicate-contact). |

Kirora matches each row to an existing contact by external ID first, then email, then phone.

### Email addresses Kirora won't add

| Problem | What to do |
| --- | --- |
| *noreply@ emails belong to a mail system, not a person* | Addresses such as `abuse@`, `postmaster@`, `webmaster@`, `security@`, `root@` and `noreply@` aren't people, and mail to them is often reported as spam. Remove them. |
| *example.co has no mail server* | The domain can't receive email, often a typo such as `gmail.co`. Correct the address or remove the row. |

### Values Kirora can't read

| Problem | What to do |
| --- | --- |
| *Phone "612345678" is not a valid number for GB (the workspace's country); write it with its country code, such as +44…* | A number without a country code is read as one in your workspace's country. If it's from another country, add its country code, such as `+33 6 12 34 56 78`. |
| *Phone "…" is not a valid number; write it with its country code, such as +447700900123* | Write the number in full with its country code. |
| *Invalid IANA timezone* | Use a time zone name such as `Europe/London` or `America/New_York`, not an abbreviation such as `GMT` or `EST`. |
| *Country "…" is not a country we know; use its two-letter code, such as GB* | Use the country's name in English or its two-letter code, such as `FR` or `GB`. |
| *Invalid locale: use a BCP 47 tag such as "fr" or "fr-CA"* | Use a language code such as `fr`, `en-GB` or `pt-BR`. |
| *Invalid calendar date fields (expected DD/MM/YYYY)* | A date doesn't match **Dates are written as**. Choose the format the file uses, and use it for every date column. |
| *"orders" is not a number* | The column is mapped as a **Number**, but this cell isn't one. Correct the cell, or change the column's **Type** to **Text**. |
| *"vip" is not a boolean* | The column is mapped as **Yes / no**, but this cell isn't yes or no (or true/false, y/n, 1/0). Correct the cell, or change the column's **Type** to **Text**. |
| *"email_consent" must be yes or no (also true/false, y/n or 1/0)* | Use one of those values in the consent column. A blank cell leaves an existing contact's consent as it is and gives a new contact none. |
| *attributes may have at most 50 keys* | The contact would end up with more than 50 attributes. Import fewer attribute columns. |
| *Text must not contain the NUL character (U+0000)* | The file holds a hidden control character, often from a copy and paste. Save it again from a spreadsheet as CSV UTF-8. |

A row can join up to 20 lists through a **Lists** column, each name up to 255 characters. A row that names more fails, and the others still import: trim its lists, or add the contact to the rest from the list's page. See [Add contacts to lists from a column](https://kirora.io/docs/guides/contacts/import-contacts#add-contacts-to-lists-from-a-column).

## Other problems

**Contacts imported, but campaigns skip them.** Importing never gives consent by itself. Map an **Email consent** column, or tick **Everyone in this file agreed to marketing email**, and say how they agreed. Addresses that unsubscribed, bounced or marked your email as spam stay suppressed, whatever the file says. See [Consent and unsubscribes](https://kirora.io/docs/guides/contacts/consent-and-unsubscribes).

**The same person appears twice in the file.** The later row updates the contact the earlier row created, and is counted as **Updated**.

**Names show odd characters, such as *José*.** The file wasn't saved as UTF-8. Save it as CSV UTF-8 and import it again: matching contacts are updated with the correct spelling.

**Test addresses didn't receive anything.** Addresses at `example.com` are test contacts. They go through every step of a campaign or journey, but nothing is delivered to them.

## Next steps

- [Import contacts](https://kirora.io/docs/guides/contacts/import-contacts) — the steps of an import
- [Manage contacts](https://kirora.io/docs/guides/contacts/manage-contacts) — edit or delete contacts after an import
- [Contact attributes](https://kirora.io/docs/guides/contacts/attributes) — attribute names and types