Module Navigation

Troubleshooting Sage 100 Integration Error: Preload or Lookup Data Setup Failure

Before the Employees entity can be read from or written to Sage 100 Construction, the provider loads a set of reference lookups from HH2, such as employee statuses, employee types, positions, unions, pay groups, fringe codes, and tax types, and it also scans the employee list itself for duplicates. If Sage 100 Construction has more than one active record sharing the same name, code, or identifier in one of these lists, or is missing a required Federal Income Tax record, this preload step fails before a single employee is read or written. Almost every message in this family ends the same way: the sync stops for this connector before any employee data moves, and you have to fix the underlying data in Sage 100 Construction before trying again.

Error Messages

Message textDirectionOccurs whenOutcomeFix
One or more errors occurred in Employee PreLoad for the Sage 100 Construction Provider. Review the logs, correct the data issue and run the Sync again.BothOne or more of the individual Employee preload lookup checks below (statuses, types, positions, unions, pay groups, fringe codes, tax types) reported a failure during the same preload pass. This is the aggregate signal raised once those checks finish; on its own it does not identify which lookup failed.Sync stoppedFind the more specific message logged earlier in the same preload and fix that data issue in Sage 100 Construction.
While reading employees from HH2 the provider encountered multiple active employees with the same version: IsSameVersion = [True or False]Write (Arcoro to Sage 100)While batch-loading every Sage 100 employee before any employee is written, two non-archived employees share the same Employee Code. This check always runs and is not gated by a scope. IsSameVersion reports whether the two records also carry the same Version value.Sync stoppedIn Sage 100 Construction, find the two employees sharing that Employee Code and correct or archive one of them.
Duplicate Employee Status records were read from HH2 with Name '[employee status name, or the record Id if matched by Id]'. Correct the data in HH2 and run the sync again.BothTwo non-archived Employee Status records share the same key. Read side: requires the Employee Type scope; compares by record Id. Write side: always runs, no scope gate; compares first by Name, then separately by Id.Sync stoppedIn Sage 100 Construction, rename or archive the duplicate Employee Status record so only one active record has that name.
Duplicate Employee Type records were read from HH2 with Name '[employee type name, or the record Id if matched by Id]'. Correct the data in HH2 and run the sync again.BothTwo non-archived Employee Type records share the same key. Read side: requires the Employee Type scope; compares by record Id only. Write side: always runs, no scope gate; compares first by Name, then by Id.Sync stoppedIn Sage 100 Construction, rename or archive the duplicate Employee Type record so only one active record has that name.
Duplicate Fringe Benefit records were read from HH2 with Code '[fringe code, or the record Id on the read side]'. Correct the data in HH2 and run the sync again.BothTwo non-archived Fringe Benefit records share the same key, gated by the Fringe Benefits scope on both sides. Read side compares by record Id (the value shown is the Id, not the Code). Write side compares by Code.Sync stoppedIn Sage 100 Construction, rename or archive the duplicate Fringe Benefit record so only one active record has that code.
Duplicate Pay Group records were read from HH2 with Name '[pay group name, or the record Id on the read side]'. Correct the data in HH2 and run the sync again.BothTwo non-archived Pay Group (Certified Class) records share the same key, gated by the Pay Group scope on both sides. Read side compares by record Id only. Write side compares first by Name, then by Id.Sync stoppedIn Sage 100 Construction, rename or archive the duplicate Certified Class record so only one active record has that name.
Duplicate Position records were read from HH2 with Code or Name = '[position Id, code, or display name]'. Correct the data in HH2 and run the sync again.BothTwo non-archived Position records share the same key. Read side: requires the Occupation scope; compares by record Id only. Write side: always runs, no scope gate; compares first by Id, then by display name (the record's Name, or its Code if Name is blank).Sync stoppedIn Sage 100 Construction, rename or archive the duplicate Position record so only one active record remains with that code or name.
Duplicate Union records were read from HH2 with Code or Name = '[union Id, code, or name]'. Correct the data in HH2 and run the sync again.BothTwo non-archived Union records share the same key, gated by the Union scope on both sides. Read side compares by record Id only. Write side compares first by Code, then by Id.Sync stoppedIn Sage 100 Construction, rename or archive the duplicate Union record so only one active record remains with that code.
The provider could find a TaxType record in HH2 for Federal Tax. The TaxType record must be named 'Federal Income Tax'. Correct the data issue in Sage 100 Construction and run the sync again.BothNo Tax Type record in Sage 100 Construction has both a Federal tax level and the exact name "Federal Income Tax". Read side only checks this when the Federal Taxes scope is enabled. Write side checks this every run, regardless of scope.Sync stoppedIn Sage 100 Construction, ensure exactly one Federal-level Tax Type record exists named exactly "Federal Income Tax".
The Sage 100 Construction Provider could not load Federal or State Tax information from HH2. Correct the data issue and run the sync again.Write (Arcoro to Sage 100)Sage 100 Construction returns zero Tax Type records of any kind. This check always runs, regardless of scope, and is checked before the Federal Income Tax name check above.Sync stoppedIn Sage 100 Construction, verify that Tax Type records exist under the payroll tax setup at all.

Confirming the Error

  1. Open the sync run in the Arcoro sync history for the connector and find the Employees entity for that run.
  2. Check the Errors, Warnings, Information, Failures, Added, Updated, and Unchanged columns for the Employees entity.
  3. Preload messages appear at the very start of the Employees entity's log, before any per-employee messages, because preload runs before any employee is read or written.
  4. Match on the fixed part of the sentence (for example, "Duplicate Union records were read from HH2 with Code or Name =") rather than the quoted value in the message, since that value varies by record.
  5. A non-zero Failures count from a preload message means something different from a normal per-record error: the whole Employees entity for that run produced no Added, Updated, or Unchanged records at all, rather than most employees succeeding with a handful of individual record errors.
  6. For the duplicate active employee version message specifically, check whether other entities in the same sync step still show normal Added/Updated/Unchanged counts. Unlike the other messages in this article, this one is not expected to stop the rest of the sync, only the Employees entity for that run.

Resolving the Error

One or More Errors Occurred in Employee Preload

  1. Open the sync log for this run and find the specific message logged earlier in the same Employee preload phase (one of the other rows in this article).
  2. Resolve the data issue identified by that specific message in Sage 100 Construction.
  3. Run the sync again.
  4. Confirm the fix worked: the Employee preload no longer logs an Error, and the Employees entity shows a normal Added/Updated/Unchanged count with zero Failures.

Duplicate Lookup Record (Employee Status, Employee Type, Fringe Benefit, Pay Group, Position, or Union)

  1. Identify which lookup the message names: Employee Status, Employee Type, Fringe Benefit, Pay Group (Certified Class), Position (Occupation), or Union.
  2. In Sage 100 Construction, open the matching setup screen for that lookup.
  3. Find the two active records sharing the name, code, or identifier quoted in the message and rename or archive one of them so only one active record remains.
  4. Run the sync again.
  5. Confirm the fix worked: the Employee preload no longer logs an Error for that lookup, and the Employees entity shows a normal Added/Updated/Unchanged count with zero Failures.

Duplicate Active Employee Version

  1. In Sage 100 Construction, search for the employee Code named in the sync log.
  2. Correct or archive one of the two employee records sharing that code so each active employee has a unique Employee Code.
  3. Run the sync again.
  4. Confirm the fix worked: the Employees entity for this run shows normal Added/Updated/Unchanged counts instead of a Failure.

Missing “Federal Income Tax” Tax Type Record

  1. In Sage 100 Construction, open the Tax Type setup and look for a Federal-level record.
  2. Confirm exactly one Federal-level Tax Type record exists and is named exactly "Federal Income Tax".
  3. Correct the name or level as needed, then run the sync again.
  4. Confirm the fix worked: the Employee preload no longer logs this Error, and Federal tax data appears for employees when the Federal Taxes scope is enabled.

No Federal or State Tax Information Available

  1. In Sage 100 Construction, open the Tax Type setup and verify whether any Tax Type records exist at all.
  2. If none exist, this is a payroll tax setup gap in Sage 100 Construction that you need to complete before the sync can run.
  3. Run the sync again once Tax Type data is available.
  4. Confirm the fix worked: the Employee preload no longer logs this Error.

When to Escalate

If any of the following occur, you may need to reach out to Arcoro support for additional assistance.

  • You confirm Tax Type records exist in Sage 100 Construction, but the sync still logs that no Federal or State Tax information could be loaded.
  • The duplicate record named in the message cannot be found in Sage 100 Construction, even after checking archived records.
  • The generic Employee PreLoad error recurs, but no more specific duplicate or tax message appears earlier in the same preload window.
  • You do not have access to edit the Sage 100 Construction setup screens and need help coordinating the data fix with your reseller or IT contact.
Was this article helpful?
0 out of 0 found this helpful