Upload of CSV File Fails

User level: Admin

---

​

Symptoms

You may see one or more of the following:

• Import stuck on Contact import in progress
• Only part of the file imports (for example “352 contacts imported”)
• Custom columns are not imported
• CSV fails repeatedly without a clear cause

​

Root Causes

Some issues prevent the import from starting (such as incorrect headers), while others may only affect specific rows or cause delays.

​

⚠️ File format or encoding problems

• File not exported as CSV UTF-8
• File edited in Excel or Numbers, which may add hidden characters
• Unsupported fonts, emojis, or non-UTF8 characters
• Wrong separators (semicolon instead of comma)
• Broken structure, for example:
  • Empty rows in the middle of the data
  • Merged cells
  • Random text blocks above or below the table

These issues can cause the import to freeze, stop early, or fail with a generic server error.

​

⚠️ Missing or incorrect headers

CloudTalk needs specific headers to process your CSV. Imports can get stuck or fail if:

• Required columns are missing (at least name and either phone or email)
• Header names do not match exactly (Name or Phone is not the same as name and phone)
• Custom columns are used, but matching custom attributes are not created in CloudTalk first. In this case, those columns may not be imported, but the rest of the file can still be processed.

​

⚠️ Phone number format

If phone numbers are invalid, affected contacts may fail to import, but the rest of the file can still be processed. Typical problems:

• Missing or incorrect country code (may lead to incorrect number formatting if the default country is not set properly)
• Extra characters in the phone field:
  • Brackets, dashes
  • Text, emojis, or extensions

​

Step-by-Step Solution

​

1. Rebuild the CSV in a clean format

The safest method:

1. Download CloudTalk’s CSV template
2. Upload the template to Google Sheets
3. Paste your data into the template
4. Make sure the table:
   • Starts in the first row
   • Has no merged cells
   • Has only one header row
5. Download as CSV in Google Sheets: File > Download > Comma-separated values (.csv)
   
6. Import this new CSV file into CloudTalk

This usually removes encoding problems and hidden characters from Excel or Numbers.

​

2. Confirm your column headers

In the Google Sheets file, check:

• You have at least:
  • name
  • phone or email
• Header names are in lowercase and match CloudTalk exactly
• There are no extra spaces before or after the header text

If you use extra columns, make sure each custom column corresponds to a custom attribute in CloudTalk.

​

3. Verify phone number format

Check a few sample rows in the phone column:

• Phone numbers can be provided either in international format (E.164), for example: +14151234567, or in local format (e.g. 090886547).
• If a number does not include a country code, CloudTalk will apply the default country code from your account settings. To ensure correct results, make sure your default country is set correctly before importing.
• You can include multiple phone numbers in one cell, separated by a colon (:), for example: +14151234567:+12125550189
• Remove:
  • Brackets
  • Dashes
  • Additional text
• If a phone number cannot be recognized as valid, that contact may fail to import.

​

4. Clean up the file

Before importing again:

• Delete empty rows in the middle and at the bottom
• Remove obvious duplicates
• Unmerge all cells
• Remove emojis or unusual characters from name or other fields
• Remove extra spaces at the start or end of cells

​

5. If you use custom columns

If extra columns from your CSV do not appear or seem to block the import:

1. Open Dashboard > Settings > General > Contacts

2. Create custom attributes that match your CSV column names 3. Make sure names match exactly (including case) 4. Save, then re-import the file

​

6. Try a small test file

To locate a specific problematic row or confirm the issue:

1. Create a new sheet with 20–50 rows copied from your original CSV
2. Download that sheet as CSV
3. Import this small file into CloudTalk

• If the small file imports correctly, the problem is likely in other rows of the original file
• If the small file is also stuck, the issue is with the structure, headers, or encoding

​

When to Contact Support

Contact CloudTalk Support only if:

• The import is stuck for more than 1 hour
• The file is clean and correctly formatted
• No new rows appear in Import History
• Re-upload also fails

Attach:

• CSV file
• Screenshots of Import History
• Error message (if any)

---

Need help or have a question? Just reach out through our Support portal — we’re here for you.