Payroll writes an employee's benefit deductions, post-tax deductions, and fringes only when both the Deduction Benefits and Fringe Benefits scopes are turned on for the connector. Every deduction and fringe is checked for a valid amount and, for pre-tax deductions and fringes, matched to a company-level benefit already set up in Payroll. If a single amount is missing or out of range, or a code cannot be matched to exactly one active company benefit, that one benefit or fringe is left out of the sync. Everything else for that employee, including other benefits, still goes through.
Error Messages
| Message text | Direction | Occurs when | Outcome | Fix |
|---|---|---|---|---|
| Benefit deduction '[deduction code]' must have a flat amount or percentage. Correct the benefit in the source system and execute the sync again. | Write | The benefit deduction has a code but no deduction cost at all, neither a flat amount nor a percentage. | Collection item skipped | Enter a flat amount or a percentage for the deduction in the source system, then re-run the sync. |
| The amount for benefit deduction '[deduction code]' must be greater than or equal to 0. Correct the benefit in the source system and execute the sync again. | Write | The deduction's coverage type is Flat Amount and the deduction cost is a negative number. | Collection item skipped | Correct the negative deduction amount in the source system to zero or more. |
| The amount for benefit deduction '[deduction code]' must be less than $999,999,999,999,999.99. Correct the benefit in the source system and execute the sync again. | Write | The deduction's coverage type is Flat Amount and the deduction cost is 999,999,999,999,999.99 or more. | Collection item skipped | Reduce the deduction amount in the source system to below the maximum. |
| The percentage for benefit deduction '[deduction code]' must be between 0 and 100. Correct the benefit in the source system and execute the sync again. | Write | The deduction's coverage type is Percentage and the deduction cost is below 0 or above 100. | Collection item skipped | Correct the deduction percentage in the source system to a value between 0 and 100. |
| Benefit fringe '[fringe code]' must have a flat amount or percentage. Correct the benefit in the source system and execute the sync again. | Write | The benefit fringe has a code but no fringe amount at all, neither a flat amount nor a percentage. | Collection item skipped | Enter a flat amount or a percentage for the fringe in the source system, then re-run the sync. |
| The amount for benefit fringe '[fringe code]' must be greater than or equal to 0. Correct the benefit in the source system and execute the sync again. | Write | The fringe's coverage type is Flat Amount and the fringe amount is a negative number. | Collection item skipped | Correct the negative fringe amount in the source system to zero or more. |
| The amount for benefit fringe '[fringe code]' must be less than $999,999,999,999,999.99. Correct the benefit in the source system and execute the sync again. | Write | The fringe's coverage type is Flat Amount and the fringe amount is 999,999,999,999,999.99 or more. | Collection item skipped | Reduce the fringe amount in the source system to below the maximum. |
| The percentage for benefit fringe '[fringe code]' must be between 0 and 100. Correct the benefit in the source system and execute the sync again. | Write | The fringe's coverage type is Percentage and the fringe amount is below 0 or above 100. | Collection item skipped | Correct the fringe percentage in the source system to a value between 0 and 100. |
| Benefit code '[code]' does not match a company benefit in Payroll. Change the benefit code in the source system or add a new company benefit in Payroll and execute the sync again. | Write | The code on a pre-tax deduction or on any fringe does not match the description of any company-level benefit in Payroll, regardless of date. This check does not run for post-tax deductions (roth 401k, roth 403b, roth 457, nontaxable fringe); those are silently skipped instead when no company benefit matches. | Collection item skipped | Change the benefit code in the source system to match an existing Payroll company benefit, or add a matching company benefit in Payroll. |
| Benefit code '[code]' does not match an active company benefit in Payroll. Change the company benefit's effective start and end dates in Payroll or add a new company benefit in Payroll and execute the sync again. | Write | The code matches a company-level benefit by description, but none of the matches are active for this record's own effective and expiration dates. Payroll requires the company benefit's start date to be on or before the record's effective date, and its end date (or no end date) to be on or after the record's expiration date. Same scope as the message above: pre-tax deductions and fringes only, not post-tax deductions. | Collection item skipped | Extend the company benefit's active dates in Payroll to cover the record's dates, or add a company benefit that does. |
| More than one company benefit with description '[code]' was found in Payroll but only one is allowed. Update the company benefits in Payroll and execute the sync again. | Write | More than one company-level benefit in Payroll shares the same description and is active for the record's effective and expiration dates. Payroll requires exactly one match. | Collection item skipped | Remove or rename the duplicate company benefits in Payroll so only one has that description for the active date range. |
| Company benefits of type HSA must have the code 'SHSA' for single or 'FHSA' for family. Rename the company benefit '[code]' in Payroll to 'SHSA' or 'FHSA' and execute the sync again. | Write | The single matching company-level benefit resolves to an HSA type, but the deduction's or fringe's code is anything other than exactly 'SHSA' or 'FHSA'. | Collection item skipped | Rename the HSA company benefit in Payroll to 'SHSA' or 'FHSA'. |
| Company benefits of a type other than HSA may not have the code 'SHSA' or 'FHSA'. Change code '[code]' to something other than 'SHSA' or 'FHSA' in the source system and execute the sync again. | Write | The single matching company-level benefit is not an HSA type, but the deduction's or fringe's code is 'SHSA' or 'FHSA'. | Collection item skipped | Change the non-HSA benefit's code in the source system to something other than 'SHSA' or 'FHSA'. |
| An employee may only have a single benefit per defined contribution type. A benefit of type '[benefit type]' already exists for this employee so the benefit with code '[deduction or fringe code]' will be skipped. Change this benefit code in the source system and execute the sync again. | Write | The resolved company benefit type is a defined-contribution type (for example 401k or HSA), and a deduction or fringe of that same type for this employee has already been matched earlier in the same sync run. Payroll allows only one benefit per defined-contribution type per employee. This check does not look at effective dates; whichever record is processed first in the run wins, even if the other record's dates are more current. | Collection item skipped | Remove the extra benefit of that same contribution type in the source system, or change its code, so the employee has only one. |
| Another benefit with the description '[description]' and type '[benefit type]' already exists for this employee with overlapping effective dates. Only one benefit with the same description and type can be active at a time. Correct the benefit in the source system and execute the sync again. | Write | Another deduction, fringe, or post-tax deduction already processed for this employee in the same sync has the same description, with effective and expiration dates that overlap this one's. For deductions and fringes the resolved benefit type must also match; for post-tax deductions only the description and the date overlap are compared. When this fires, both the newly processed record and the earlier one it collided with are left out of the sync, not just the second one. | Collection item skipped (both colliding records) | Correct the effective and expiration dates, or the description, on one of the two overlapping benefits in the source system so they no longer conflict. |
| The post-tax deduction [deduction code] has an amount that exceeds either the Total Amount or the Annual Limit in Payroll. Adjust the amount in the source system or the limits in Payroll and execute the sync again. | Write | Applies only to a post-tax deduction with coverage type Flat Amount. Fires when the rounded flat amount is greater than the Total Amount or the Annual Limit already recorded on the matching Payroll deduction. Those two limits are never set by this sync; they only exist if someone entered them manually in Payroll. This means the error can only appear on an update to a deduction that already has a limit configured, never on the very first sync of a new one. | Collection item skipped | Lower the deduction amount in the source system, or raise the Total Amount or Annual Limit on the matching deduction in Payroll. |
Confirming the Error
- Open the sync execution for your connector in Sync History.
- Find the step for the Payroll connector and open the Employee entity row.
- Check the Errors column for that entity. A non-zero count means at least one employee or benefit hit a problem; the employee-level sync can still show Added or Updated even when one benefit was skipped, since only that one item is dropped.
- Open the errors list for the entity and match on the fixed part of the sentence, for example "must have a flat amount or percentage" or "does not match a company benefit in Payroll," not on the code or description in quotes.
- Note which employee and which benefit code or description the message names, since the fix is scoped to that one record.
- A non-zero Failures count for this entity is not caused by anything in this article; every message here is logged as an Error against one benefit, not a Failure.
Resolving the Error
Amount and Percentage Errors (Missing, Negative, Too Large, or Out of 0 to 100)
- Open the employee's benefit deduction or fringe in the source system.
- Confirm a flat amount or a percentage is entered, matching the coverage type on the record.
- Correct the value so it is zero or greater, and under the maximum of 999,999,999,999,999.99 for flat amounts, or between 0 and 100 for percentages.
- Re-run the sync and confirm the benefit or fringe no longer appears in the errors list for that employee.
Benefit Code Does Not Match, Is Inactive, or Is Duplicated in Payroll
- Open Company Benefits in Payroll.
- Confirm a company benefit exists whose description exactly matches the code coming from the source system.
- If it is missing, add it. If it exists but is not active for the dates on the employee's deduction or fringe, extend its effective start or end date.
- If more than one company benefit shares that same description and date range, rename or remove the extra one so only one remains.
- Re-run the sync and confirm the benefit moves out of the errors list.
HSA Code Mismatch ('SHSA' or 'FHSA')
- Ask the Payroll administrator to check the company benefit's type in Payroll.
- If the type is HSA, rename the company benefit's code to exactly 'SHSA' for single coverage or 'FHSA' for family coverage.
- If the type is not HSA, change the deduction or fringe code in the source system to something other than 'SHSA' or 'FHSA'.
- Re-run the sync and confirm the record no longer errors.
Duplicate Contribution Type or Duplicate Description
- Review the employee's benefits in the source system for the code named in the error.
- For the defined-contribution-type message, confirm the employee has only one active benefit of that type (for example only one 401k). Remove or recode the extra one.
- For the overlapping-description message, find the two benefits, fringes, or post-tax deductions with the same description and type, and adjust one's effective or expiration date so the date ranges no longer overlap, or correct the description on one of them.
- Re-run the sync and confirm both records now sync (both were held back, not just the one named in the error).
Post-Tax Deduction Amount Exceeds a Payroll Limit
- Ask the Payroll administrator whether a Total Amount or Annual Limit is set on that post-tax deduction in Payroll.
- Either raise that limit in Payroll, lower the deduction amount in the source system to fit under it.
- Re-run the sync and confirm the deduction updates without the error.
When to Escalate
If any of the following occur, you may need to reach out to Arcoro support for additional assistance.
- The error still appears after the source data and the Payroll company benefit setup have both been checked and corrected.
- The message text in the log does not match any row in the table above.
- The entity shows a non-zero Failures count instead of an Errors count for these benefits, since that points to something outside this article.
- The message text looks like it originated from Payroll itself rather than from one of the sentences above.