File issues
| Problem | Cause | Fix |
|---|---|---|
| File too large | CSV exceeds 50MB or 50,000 rows | Split into smaller files. Import in batches |
| Wrong file type | Uploaded .xlsx, .xls, or .txt | Export as .csv from your spreadsheet application |
| Encoding errors | File saved as ANSI, ISO-8859, or other non-UTF-8 | Re-save as UTF-8 CSV. In Excel: Save As → CSV UTF-8 |
| File won’t upload | Browser timeout or connection issue | Try a smaller file, clear browser cache, or use a different browser |
Formatting problems
| Problem | Cause | Fix |
|---|---|---|
| Columns not recognized | Header names do not match HoopAI fields | Use the mapping step to manually assign columns. See CSV format guide |
| Date fields showing wrong values | Ambiguous date format (01/02/2024 — Jan 2 or Feb 1?) | Use YYYY-MM-DD format to eliminate ambiguity |
| Phone numbers missing country code | Numbers like 5551234567 without +1 | Add country code prefix. Use E.164 format: +15551234567 |
| Phone parsed as scientific notation | Excel converts long numbers to 5.55E+09 | Format the phone column as Text in Excel before saving |
| Tags not importing | Tags column contains invalid formatting | Use comma-separated values in quotes: “tag1, tag2, tag3” |
| Special characters garbled | Non-UTF-8 encoding | Re-save file as UTF-8. Check for accented characters (é, ñ, ü) |
| Empty rows imported | Blank rows in the CSV | Remove empty rows before importing |
Duplicate handling
| Scenario | What happens | How to control |
|---|---|---|
| Email matches existing contact | Depends on your duplicate setting | Choose Skip, Update, or Create New during import |
| Phone matches existing contact | Same as email matching | Same options |
| Both email and phone match different contacts | May create confusion | Clean your list before import — deduplicate by email first |
Duplicate options explained
- Skip — the row is ignored and the existing contact is unchanged
- Update — the existing contact’s fields are updated with the CSV data (non-empty fields only)
- Create New — a new contact is created even if duplicates exist (not recommended)
Missing required fields
Every row needs at least one identifier (email or phone). Rows missing both are skipped. Common missing field issues:| Issue | Fix |
|---|---|
| Rows with no email or phone | Add at least one identifier per row, or remove the row |
| Required custom fields missing | Make sure your CSV includes columns for any required custom fields |
| Name fields empty | Not technically required, but contacts without names are hard to identify |
Custom field mapping failures
| Problem | Cause | Fix |
|---|---|---|
| Custom field not appearing in mapping | Field key does not match column header | Use the field’s key (not display name). Check in Settings → Custom Fields |
| Dropdown values not matching | CSV value does not match the dropdown options exactly | Ensure exact match including case and spacing |
| Number field receiving text | CSV contains non-numeric data in a number column | Clean the data — remove currency symbols, commas, text |
| Date field not populating | Date format not recognized | Use YYYY-MM-DD |
Import stuck or timed out
| Symptom | Cause | Fix |
|---|---|---|
| Import shows “Processing” for hours | Very large file or server load | Wait up to 1 hour for large imports. If still stuck, contact support |
| Import completed but contacts missing | Rows were skipped due to errors | Check the import results report — it shows skipped rows and reasons |
| Import succeeded but fields are empty | Column mapping was incorrect | Re-import with correct column mapping |
| Partial import | File had errors partway through | Fix the reported errors and re-import the remaining rows |
Import results report
After every import, HoopAI generates a results summary:- Total rows processed
- Successfully imported
- Skipped (duplicates)
- Failed (errors)
- Download error report — a CSV listing failed rows with the specific error for each
Best practices
Always do a test import first
Always do a test import first
Import 5–10 rows first to verify your formatting and column mapping before importing the full list.
Clean data in your spreadsheet first
Clean data in your spreadsheet first
Remove empty rows, fix phone formats, standardize dates, and deduplicate before exporting to CSV.
Keep a backup of the original file
Keep a backup of the original file
Save a copy of your CSV before importing, in case you need to reference or re-import.
Tag imported contacts
Tag imported contacts
Apply a tag during import (e.g., “March 2024 Import”) so you can easily find and manage them later.