If your CSV import is stuck, partially imported, or failing with errors, this guide helps you diagnose formatting issues, queue delays, missing fields, and other common causes.
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
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
nameandphone)Header names do not match exactly
(
NameorPhone numberis not the same asnameandphone)Custom columns are used, but matching custom attributes are not created in CloudTalk first
Phone number format
If phone numbers are invalid, the import can fail or stop partway through.
Typical problems:
No international format (E.164), for example numbers without country code
Extra characters in the phone field:
Spaces, brackets, dashes
Text, emojis, or extensions
Step-by-Step Solution
1. Rebuild the CSV in a clean format
The safest method:
Download CloudTalk’s CSV template
Upload the template to Google Sheets
Paste your data into the template
Make sure the table:
Starts in the first row
Has no merged cells
Has only one header row
Download as CSV in Google Sheets:
File > Download > Comma-separated values (.csv)
Import this new CSV file into CloudTalk
This usually removes encoding problems and hidden characters from Excel or Numbers.
For full import step-by-step instructions including the download of the CSV template and import steps, see How to import contacts to CloudTalk from a file
2. Confirm your column headers
In the Google Sheets file, check:
You have at least:
namephone
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:
Use E.164 format, for example:
+14151234567Keep only digits and the
+signRemove:
Spaces
Brackets
Dashes
Additional text
Only one phone number per cell
If numbers do not start with +, CloudTalk will try to apply your default country code. If the number itself is incomplete, this can cause errors.
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
nameor other fieldsRemove 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:
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:
Create a new sheet with 20–50 rows copied from your original CSV
Download that sheet as CSV
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 Report an Issue
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)