CSV: common errors
Common CSV import failures, product hints, and fixes.
integrationcsv
Audience: Organization admin / academic ops · Applies to: SaaS / private deployment
Goal: Fix files quickly from validation or batch errors.
Error map
| Symptom / hint | Likely cause | What to try |
|---|---|---|
| Email already exists | Duplicate in the org, or leftover from an old import | Change email; confirm whether you meant to update an existing account |
| Invalid email format | Spaces, full-width symbols, missing @ | Clean format and re-import |
| Invalid / missing class code | Class not created, or code case/spaces differ | Import classes first; normalize codes |
| Role mismatch | Value not allowed by the template | Match the template enum |
| Required empty | Missing value or shifted columns | Check headers and merged cells |
| Garbled encoding | Not UTF-8 | Re-save as UTF-8 CSV and re-upload |
| Password policy fail | Too short or illegal characters | Fix the initial-password column |
| Membership failed | Person exists but class code wrong, or person not imported yet | Repeat order: classes → people → members |
| Insufficient permission | Current admin role is read-only | Use an owner/admin account |
UI copy may vary slightly—row-level errors in batch detail win.
Triage order
- Look at row numbers; edit only failed rows.
- Confirm headers were not renamed.
- Confirm import type matches file content (do not upload a student file as teachers).
- Pass a small sample before full load.
If still failing, provide
- Import batch ID
- Import type
- 1–2 redacted sample rows (remove real phones; names optional)
- Full error text
Back to First import or Templates and fields.