Overview
When we receive a roster, election, or deduction file, Benepass checks each employee or enrollment entry, called a record, against the required data and enrollment rules. If a record does not meet the required data or enrollment rules, an error will appear in the error report.
Use the error message to identify the issue, correct the source data when applicable, and resubmit the file. Some errors may require assistance from Benepass Support.
Review the sections below to learn more about each error type and how to resolve it.
File and worker data errors
This field cannot be null
A required field is blank or contains a null value.
How to resolve
Review the affected record and provide a valid value for the required field. Confirm that the source system is populating the field before generating the file again.
SSN: <reason>
The Social Security number failed validation. The SSN is displayed in a masked format, such as ***-**-1234, to protect sensitive information.
How to resolve
Review the SSN in the source system and confirm that it:
Is valid and formatted correctly
Belongs to the correct employee
Does not contain extra spaces or unsupported characters
Correct the value and resubmit the file.
DOB: Worker must be at least 18 years old
The employee’s date of birth did not pass the age validation check. For privacy and security, the date-of-birth value is redacted in the report.
How to resolve
Review the employee’s date of birth in the source system. Confirm that the date is accurate and that the employee meets the minimum age requirement.
Hire/Termination date in the future
A hire date or termination date contains a date later than the current date.
How to resolve
Review the affected date in the source system and confirm that it is correct. Future dates should only be included when they are supported by the applicable file requirements and processing rules.
Email must be unique among active employees
The employee’s primary email address is associated with more than one active employee.
How to resolve
Each active employee must have a unique primary email address. Review the duplicate records and update the source data with the correct email address for each employee.
Roster and election file errors
No election row for this Payroll ID & Benefit Type was found in the latest election file
The employee appears in the roster, but Benepass could not find a matching election record in the latest election file for the specified Payroll ID and benefit type.
How to resolve
Confirm that:
The Payroll ID matches exactly between the roster and election files
The benefit type is spelled and formatted correctly
The employee’s election is included in the latest election file
The latest election file was successfully delivered and processed
If the employee should not be enrolled, confirm that the roster and election data are intentionally different.
Not found in roster or failed roster validation
The employee’s unique ID in the election file could not be found in the roster, or the corresponding roster record failed validation.
How to resolve
Confirm that:
The unique ID matches exactly between the roster and election files
The employee is included in the latest roster
The roster record does not contain validation errors
There are no extra spaces, formatting differences, or duplicate IDs
Correct the source data and resubmit the applicable file.
Enrollment record errors
An election already exists for this benefit and employee. Check if there's an existing PayrollEnrollment with different start_date
A duplicate enrollment was detected for the same employee and benefit. This commonly occurs when the same enrollment ID exists with different start dates.
How to resolve
Review the employee’s enrollment records and identify the duplicate enrollment. The duplicate record must be removed or corrected so that only the intended enrollment remains.
If you need help identifying the correct record, contact Benepass Support.
Failed to match a user to this worker, since another worker is already tied to the matching user…
Benepass found a user-matching conflict because the same Payroll ID is associated with more than one worker.
How to resolve
Review the affected Payroll IDs in the source system and confirm that each employee has a unique ID. Because this issue may involve existing account relationships, contact Benepass Support for remediation after correcting any source data issues.
Deduction file errors
Payroll deduction amount has changed…
The deduction amount guard was triggered because the submitted deduction amount is different from the amount previously received for the employee.
This validation helps prevent unexpected changes from being processed without review. When this validation is triggered, the updated deduction is blocked from processing, so the funds will not be added to the employee’s benefits balance until Benepass reviews and unblocks the deduction.
How to resolve
Confirm whether the deduction amount change is intentional.
If the change is incorrect, review and correct the source payroll data.
If the change is intentional, contact Benepass Support so the deduction can be reviewed and unblocked.
Include the employee’s Payroll ID, benefit type, previous deduction amount, new deduction amount, and reason for the change when contacting Support.
When to contact Benepass Support
Contact Benepass Support when:
You implement one of the above fixes by updating your system of record, and the issue is not fixed in Benepass within 48 hours.
OR if:
The error refers to duplicate or existing enrollment records
A user-matching conflict cannot be resolved in the source system
A valid deduction change is blocked by the deduction amount guard
You are unsure which enrollment or account record should remain
When contacting Support, include the error message, affected Payroll ID, file name, and the date the file was submitted.