Troubleshooting
Import Troubleshooting
Import problems fall into three groups: the file won't upload, the columns won't map, or individual rows won't validate. This page covers all three, plus what to do when an import finishes but the result isn't what you expected.
The file won't upload
| Message | Cause | Fix |
|---|---|---|
Invalid file type. Allowed: .csv, .xlsx, .xls | The file isn't a spreadsheet — often a .numbers, .ods, .pdf, or .txt | Open it in your spreadsheet app and re-save as CSV |
File too large … Maximum is 25MB | Over the size limit | Split it, or export fewer columns |
File is empty or too small to parse | A zero-byte or truncated download | Re-export from the source system |
The file has no data rows | Only a header row, or every row is blank | Check you exported the data, not just the layout |
The spreadsheet is empty | The first sheet of the workbook has no rows | Move your data to the first sheet |
Too many imports. Please wait before starting another. | More than 5 imports started in an hour | Wait, then continue |
Maximum 5 active imports at a time | Five imports are sitting unfinished | Open them from the history and finish or cancel them |
Only administrators and executives can import data | Your role can't run imports | Ask an administrator to run it |
Only some columns were mapped
The mapping screen tells you how many of your columns were matched. Anything unmapped is left for you to set by hand from the dropdown — an unmapped column is not an error, it just won't be imported unless you assign it.
| Symptom | Cause | Fix |
|---|---|---|
| A column shows Skipped (sensitive) and has no dropdown | The header looks like salary, bank, or government-ID data | Expected. These are never imported — add them to the employee's HR record afterwards |
| A field is greyed out in the dropdown | It's already taken by another column | Set the other column to — Skip this column — first |
| Preview Import stays disabled | A required field isn't mapped | Map every field marked with an asterisk |
| Barely anything auto-mapped | Unusual headers, or the header row isn't row 1 | Delete any title rows above the headers and re-upload |
| The wrong platform was detected | Two platforms have similar layouts | Ignore the badge and correct the mappings by hand; the badge is only a suggestion |
Rows failed validation
These appear in the preview, and in the error log on the import's detail page, with the row number from your file.
| Error | Cause | Fix |
|---|---|---|
firstName is required / lastName is required / email is required | The cell is empty, or the column is mapped to the wrong field | Fill the cell, or fix the mapping |
Invalid email format | Not a valid address — often a stray space, or a placeholder like n/a | Correct the address; every employee needs a real, unique one |
Invalid date format | The date couldn't be read | Reformat the column as YYYY-MM-DD |
Invalid number | Text in a numeric column, such as N/A in a leave balance | Clear the cell or enter a number |
Employee "…" not found in this organization | A Leave History row references someone who hasn't been imported | Import employees first, then the leave history |
Start and end dates are required | A leave row is missing one of its dates | Supply both |
Name is required | A full-name column was blank when it was split into first and last | Fill in the name |
Rows were skipped
Skipped means the record was already there.
| Skip reason | What happened |
|---|---|
User with email … already exists | Someone in your organization already has that address. The existing person is left exactly as they were |
Department "…" already exists | Matched an existing department by name, ignoring case |
If you were expecting an import to update existing people, it won't — import creates records, it never overwrites them. Edit those people directly from Managing Users.
The import finished but the data looks wrong
| Symptom | Cause | Fix |
|---|---|---|
| Dates are a day or a month out | A day-first file (01/02/2024) read as month-first | Roll the import back, reformat the date column as YYYY-MM-DD, re-import |
| Everyone's employment type is Full time | The value in your file wasn't recognized, so the default was applied — this raises a warning, not an error | Check the warnings; re-import with values like Full-Time, Part-Time, Contract, Intern, Casual |
| Managers aren't set | The manager column wasn't mapped, or the manager isn't in the file and wasn't already in the organization | Managers can be an email or a First Last name — make sure the manager exists |
| Departments you didn't create appeared | Any department named in an employee file is auto-created | Expected. Rename or deactivate them in Departments |
| A value is cut short | It exceeded the field's maximum length and was truncated — this raises a warning | Shorten it in the source file and re-import, or edit the record |
| Leave requests are duplicated | The same Leave History file was imported twice | Roll the second import back |
| Only 10,000 rows imported | The per-file row limit | Split the file and run several imports |
Direct connections
Connection-specific errors are covered on Direct Connections.
Undoing an import
Any completed import can be undone for 72 hours — see Rollback & Import History. If the window has closed, remove the records individually from Managing Users.
Still stuck
Take note of the import's date, file name, and the row numbers that failed, then contact support from Settings → Support. Every import is audit-logged, so those details are enough to trace exactly what happened.
Rollback & Import History
Reading an import's result page, the row-by-row error log, and how to undo a completed import within the 72-hour rollback window.
Leave Management Overview
Core concepts behind leave in BookYourPTO — leave types, balances and buckets, the fiscal year, how business days are counted, and the request-to-approval lifecycle.