What do the errors in my Tilt import log mean?

Quick answer

After you test or upload a file, download the import log to see what happened row by row. The summary tells you how many rows imported successfully, how many processed with errors (imported, but one or more fields were skipped), and how many failed to process (the whole row was rejected). Errors fall into three levels — file, header, and row — and each error message points to the exact field and reason so you can fix your file and re-upload.

Who this applies to / Prerequisites

You must be an HR user with admin access in Tilt. Employees and non-admin HR users cannot access the Uploads page or the import log.
The import log is only available after a file has been tested or uploaded.

Steps

From the HR Dashboard, go to the Uploads page (under Org Settings in the left navigation bar).
Click the kebab menu (the three vertical dots) on the upload row.
Click Download Import Log.
Read the summary to see how many rows succeeded, processed with errors, or failed to process:

Processed with errors — the row imported, but one or more fields were skipped or couldn't be updated. Review the field-level messages for that row.
Failed to process — the entire row was rejected and none of its data imported. Correct and re-upload it.

Use the error levels and messages below to fix your file, then upload it again.

Error levels

Error Type	Explanation and Recommendation
File level error	The entire file failed to process. Review the import template and field guide to confirm your file is structured correctly and saved in an acceptable format.
Header level error	One or more column headers are incorrect or a required header is missing. Headers must match the template exactly, including punctuation — for example, "Enrolled in Health Benefits?" requires the question mark. Note: an incorrect header on an optional column silently skips that column and isn't always logged, so double-check optional headers even when the log looks clean.
Row level error	Data in a specific row is formatted incorrectly. Common causes: unexpected formats, a missing required field (such as a blank email), an invalid value for the field, a Salary/Salary Period mismatch, or a duplicate Employee ID. The log identifies the row number and Employee ID.

How to read a row-level error

Row-level errors follow this pattern: the row number in your file, the Employee ID and name, the field with the problem, and the reason it failed. For example, a row showing "Email: This field may not be blank" means that row's Email field is empty. Correct the field in your file and re-upload.

Common error messages and what they mean

Message in the import log	What it means	How to fix it
[column name]: the header was not recognized.	The column header doesn't exactly match the template. Even one character off — a missing question mark, extra space, or typo — causes this.	Copy the header directly from the template so it matches exactly, including punctuation and capitalization.
* : the header was not recognized. (no column name shown)	Your file has an empty or extra column — often a stray column with no header, or leftover data outside the template's columns.	Delete any blank or extra columns so the file contains only the template's columns.
This field may not be blank.	A required field (such as Email) is empty for that row.	Fill in the missing value and re-upload. Every employee needs a value in each required field.
Value '[X]' is not a valid choice.	The field only accepts specific values, and yours isn't one of them.	Check the field guide for accepted values and update your file to use one exactly as written.
Duplicate Employee ID	Two rows share the same Employee ID, or the ID conflicts with an existing record.	Give each employee a unique Employee ID. If a name or email changed, keep the same Employee ID so history stays linked to one account.
Errors mentioning constraint, duplicate key value, or other database language	A system-level error, not something you can fix in your file.	Send the full error text to your Customer Success Manager as-is — no file changes needed.

What if it doesn't work

The log shows no errors, but my data didn't update: A column header likely didn't match the template, so the column was silently skipped. Older data from a previous import still displays, making the upload look successful. Fix the header to match exactly (including punctuation) and re-upload.
I fixed the error, but it appears again on the next upload: The correction was likely made in Tilt but not in the source file (or the feed generating it), so each upload re-introduces it. Update the file itself — or the system exporting it — not just the record in Tilt.
The log says a row failed but doesn't say which one: Check the row-level details for a row number and Employee ID. If the error shows "* :" with no column name, look for blank or extra columns instead.
The error mentions "constraint," "duplicate key," or other database language: This is a system-level error you can't fix by editing your file. Send the full error text to your Customer Success Manager as-is.
You're importing via SFTP: Import results come by email notification instead of the on-screen log, but the error messages follow the same patterns above.

Limits and exceptions

Only HR users with admin access can view the Uploads page and download the import log.
The import log is only available after a file has been tested or uploaded. There's no log for a file that was never submitted.
Column headers must match the template exactly, including capitalization and punctuation. There is no fuzzy matching — a single character difference means the column will not import.
Optional columns with incorrect headers are skipped without importing data, and this isn't always logged as an error.
Required fields cannot be blank. A row with a blank required field (such as Email) will not import.
Fixing an error in the log does not retroactively import the data — you must correct the file and upload it again.
System-level errors (database or constraint errors) can't be resolved by editing your file and must be escalated to Tilt.

What do the errors in my Tilt import log mean?

Decode every error type — file, header, and row-level — and fix your import file before uploading again.

Error levels

How to read a row-level error

Common error messages and what they mean