Managing Contribution Validation Errors

To ensure that contribution & loan repayments are error-free, Vestwell applies a number of validation rules to each contribution.  Validation errors are flagged for review and action directly in the portal.  In some cases, validations may identify unallowable contributions.  In those cases, the unallowable contributions are flagged so that the sponsor can remedy the issue or return funds to participants, as appropriate.  

In this article, we are focusing on contributions processed using the Vestwell portal. We will review the portal experience when validation errors occur.  We will also provide a breakdown of the validations that occur with common resolution steps.

Validation Errors on the Contribution Grid

Vestwell directly evaluates contribution data for incomplete/invalid data in the contribution grid.

If you manually enter contributions & loan payments into the contribution grid, required fields, as well as invalid data within an area will be highlighted in red as you enter data.  You won't be able to submit your contribution until all red fields are eliminated. 

If you've uploaded a contribution file into Vestwell, fields that have triggered an error will be highlighted in red. An error counter will display the number of errors on the screen that require your action.  The error counter will reduce as you resolve validation errors. As long as errors are detected, the "Send and Validate" button will be grey and disabled.

On the contribution grid, the data is evaluated in multiple steps. You must work through all red highlighted fields until the error counter is zero (0), then press the blue "Send & Validate" button.  Each time you press "Send & Validate," the system evaluates the data for additional errors until none remain.


For each error displayed in the grid, you can resolve/correct the data issue directly on the screen.  If you don't have the information to fix the error, you can choose to exclude the row instead.  


If you choose to "Exclude Row," any contribution associated with that row will be unallowed and removed from the contribution. 

On the Review Submission page, you will see a final recap of any excluded contributions in the section called "Contribution Adjustments - Action Needed." You will only see this if you exclude a row that had a contribution associated with it.


At any time in this process, you can cancel or edit the submission if you find that the contribution adjustment resulted from a typo or other clerical error.

Employers are responsible for taking action to either 1) resolve the contribution error and re-submit the impacted contributions OR 2) refund money to the employee if the deduction was taken in error or the contribution cannot be completed.

Summary of Vestwell Contribution Grid Validations





Missing SSN

SSN is missing from the submission

UI Validation occurs


Action Options: The sponsor must enter a correctly formatted SSN or exclude a row to continue.


Bad SSN format 

SSN is not properly formatted with nine digits

UI Validation occurs

Action options: The sponsor must update to an adequately formatted SSN or exclude row to continue.


Invalid SSN

Invalid SSN:

- all the same digits

- 0s in positions 1-3 or 4-5 or 6-9

- 123-45-6789

- 987-65-4321


UI Validation occurs

Action options: Sponsor must update to a valid SSN or exclude row to continue.


Duplicate SSN

More than one record on submission with the same SSN 

UI Validation occurs

Action options: Sponsor may only have one unique SSN record remaining to continue. At least one record must be excluded.


Missing names

First name or last name is missing from submission (SSN and names are always required)

UI Validation occurs

Action options: Sponsor must enter a name or exclude row to continue.




Unrealistic DOB

DOB does not fall into 10 to 100 year old age range  

UI Validation occurs

The sponsor must enter a valid date or select the current DB value to continue.   


Bad DOB format

DOB is not in a valid date format 


UI Validation occurs

Sponsor must enter a valid date or exclude a row to continue.


Unrecognized Employee

SSN on the submission does not match anyone in the plan 

UI Validation occurs

The sponsor must add the participant or exclude the row to continue.


Bad DOH format - required field 

The date is not in a valid date format

UI Validation occurs

Sponsor may enter a new day, exclude the row, OR if we have a record of a DOH, that date will be presented as an option.


Bad DORH format

Bad DOT format - Optional fields

The date is not in a valid date format

Message on validation: Invalid {type of date} date format 

2 cases: when we had a date from before and when we did not 

UI Validation occurs

- Must enter a valid date 

  Example coming soon

Bad Zip and Bad State

Zip or State fields are not properly formatted 


UI Validation occurs

- Must enter a valid format for zip code (5 digit or 9 digits with or without dash)

- Must be a valid 2 character abbreviation or full state name. 

Bad Zip FormatBad_ZIP_Format.png 

Bad contribution format

A negative contribution. 

Other non-number values get normalized into Null 

Values with more than 2 decimal places get rounded to 2 decimal places

UI Validation: ensure that a positive number is entered   

Example Coming Soon

If you have any questions, please reach out to us at