Module Navigation

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

Before the sync reads or writes a single employee, the Sage 300 CRE provider loads a set of lookup lists from HH2, things like departments, unions, employee types, pay types, and tax types. This is called preload. If any of these lookup lists has bad data, most commonly two active records sharing the same key, or a required tax record is missing, the preload step fails and the whole sync run stops before any employee is touched. Nothing is added, updated, or changed for that run.

Error Messages

Message textDirectionOccurs whenOutcomeFix
One or more errors occurred in Employee PreLoad for the Sage 300 CRE Provider. Review the logs, correct the data issue and run the Sync again.Read and WriteThis is the umbrella failure. It fires once any one of the individual lookup list loads (Department, Union, Union Local, Union Class, Certified Class, Employee Type, Employee Status, Fringe, Rate Codes/Pay Type) reports a problem, after every lookup list has finished loading.Sync stopped. No employees are read or written for this run.Scroll up in the log to the specific error logged just before this one and fix that data issue.
The Sage300 CRE Provider could not load Federal or State Tax information from HH2. If this problem persists please contact Arcoro support.Read and Write (behaves differently in each, see next column)Fires only when the Federal Taxes or State Taxes scope is enabled for the run, and HH2 returned zero Tax Type records at all. On a read, this stops the sync immediately by itself. On a write, it is logged as an error and the sync stops shortly after, once the overall preload check fails.Sync stopped. No employees are read or written for this run.Confirm HH2 has Tax Type records at all. If none exist, escalate.
The Sage300 CRE Provider could not find any TaxType records in HH2 with a Code value of FWH. (Federal Tax Type record not found).Read and WriteFires only when the Federal Taxes scope is enabled for the run, Tax Type records exist in HH2 (otherwise the tax load message above fires instead), and none of those records has a Code of FWH.Sync stopped. No employees are read or written for this run.In Sage 300 CRE, add or correct a Tax Type record with Code FWH representing federal withholding.
The Sage 300 CRE Provider encountered a duplicate [lookup list name] with key: '[key value]' in the Employee Write Service. The Sync will not be able to continue. Correct the data in HH2 and attempt the Sync again.Read and WriteFires while loading one specific lookup list when two active (not archived) records in that list share the same lookup key.Sync stopped. The duplicate record itself is skipped from that lookup list at the moment it is found, but the run still fails afterward once all lookup lists finish loading.In the named lookup list in Sage 300 CRE, find the two active records sharing that key and correct or archive one of them.
While reading employees from HH2 the provider encountered multiple active employees with the same version: IsSameVersion = [true or false]Write onlyFires while loading the employee list itself, after every lookup list has already loaded successfully, when two active (not archived) employees share the same employee Code.Sync stopped immediately at the moment the duplicate is found. No employees are written for this run.In Sage 300 CRE, find the two active employee records sharing that Code and correct or archive one of them.

Lookup Lists That Can Appear in the Duplicate Key Message

The duplicate key message names the specific lookup list in place of [lookup list name]. The exact wording differs slightly between a read and a write, but it is the same underlying list in Sage 300 CRE:

  • Employee Type (read) or Employee Types (write)
  • Employee Status
  • Rate Codes (this is the Pay Type list in Sage 300 CRE)
  • Union (read) or Unions (write)
  • Union Local (read) or Union Locals (write)
  • Union Class
  • Department (read) or Departments (write)
  • Certified Class
  • Fringe (read) or Fringe Codes (write)

Confirming the Error

  1. Open the sync run in Sync History.
  2. These are setup-stage messages. They are recorded before any per-employee rows appear in the log, since preload runs once for the whole connector before a single employee is processed.
  3. Check the per-entity counts on the People/Employees row: Errors, Warnings, Information, Failures, Added, Updated, and Unchanged. For this family, Added, Updated, and Unchanged will all be zero, because preload failed before any employee could be processed. A non-zero Failures count on the run confirms the sync did not complete normally.
  4. Match on the fixed part of the sentence, not the quoted values. For example, match on "encountered a duplicate" and "in the Employee Write Service", not on the specific lookup list name or key.
  5. Check for more than one duplicate key message in the same run. More than one lookup list can have a duplicate at the same time.

Resolving the Error

One or More Errors Occurred in Employee Preload

  1. This message by itself does not name the data problem. Look for the specific message logged alongside or just before it in the same run and resolve that one.
  2. If no other specific message appears in the log for this run, escalate.

Could Not Load Federal or State Tax Information / No FWH Tax Type Record Found

  1. In Sage 300 CRE, confirm that Tax Type records exist for the company at all.
  2. If no Tax Type records exist in HH2, this needs escalation.
  3. If Tax Type records do exist, confirm there is one with a Code of FWH representing federal withholding. If it is missing or was renamed, correct it in Sage 300 CRE.
  4. Re-run the sync. Confirm the fix worked by checking that this message no longer appears and that the Employees row now shows Added, Updated, or Unchanged counts greater than zero.

Duplicate Lookup Key

  1. Read the entity name out of the message text and match it against the list above to identify the Sage 300 CRE list it refers to.
  2. In Sage 300 CRE, open that list (for example, Departments, Unions, Union Locals, Union Classes, Certified Classes, Employee Types, Employee Statuses, Fringe Codes, or Pay Types) and search for the key value quoted in the message.
  3. Confirm two active, non-archived records share that key. Correct or archive one of them so the key is unique.
  4. Re-run the sync. Confirm the fix worked by checking that this message no longer appears for that lookup list.

Duplicate Active Employee Version

  1. In Sage 300 CRE, search for active employee records sharing the Employee Code called out by the sync (the message itself does not include the code, only whether the two records share the same version).
  2. Confirm whether one of the two records should be archived, or whether the employee record was duplicated in error.
  3. Correct or archive the duplicate in Sage 300 CRE.
  4. Re-run the sync. Confirm the fix worked by checking that this message no longer appears and that the Employees row now shows Added, Updated, or Unchanged counts greater than zero.

When to Escalate

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

  • The tax load failure message explicitly tells you to contact Arcoro support if it persists after confirming HH2 has Tax Type data. Escalate rather than continuing to troubleshoot.
  • If the duplicate active employee version message keeps recurring after you have corrected what looks like a duplicate Employee Code in Sage 300 CRE, escalate. The log does not show which two records collided, only whether they had the same version.
  • If you cannot locate or edit the named lookup list itself, for example, if it is generated automatically inside Sage 300 CRE, escalate.
  • If the umbrella preload message appears with no other specific message anywhere in the same run, escalate. Something failed preload without logging a data issue.
Was this article helpful?
0 out of 0 found this helpful