Before Arcoro can read or write any Acumatica employees, it first loads a set of reference lists from Acumatica, such as Union Locals, Workers Compensation Codes, Occupations, and Work Locations. If any one of these reference lists contains two records that share the same identifying value, Arcoro cannot safely tell the two records apart. When that happens the entire employee sync for that run is stopped before any employee record is read or written. This is a data setup issue in Acumatica, not a problem with any individual employee.
Error Messages
| Message text | Direction | Occurs when | Outcome | Fix |
|---|---|---|---|---|
| Failures on Preload | Read and write | One or more of the reference lists (lookups) loaded before an Employee read or an Employee write fails to load cleanly. For this article, the underlying cause is always a duplicate key found in one of the lookups described by the two messages below. | Sync stopped. No employees are read or written for that run. | Escalate. Find the duplicate-key message logged in the same preload and act on that message instead. |
| The Acumatica Provider encountered a duplicate [lookup type] with key: '[duplicate key value]' in the Employee Read Service. Contact support to resolve this issue. | Read, for Union Local, Workers Compensation Code, and Occupation. Also occurs on Write for Work Location and Workers Compensation Code because of a labeling defect in the provider; see How to confirm below. | The named lookup returns two or more records that share the same key. See Which lookups can produce this for the key used by each lookup. | The duplicate record is dropped from that lookup, which marks the whole preload as failed. Sync stopped, zero employees processed. | Escalate. Support must identify and correct the duplicate record in Acumatica. |
| The Acumatica Provider encountered a duplicate [lookup type] with key: '[duplicate key value]' in the Employee Write Service. Contact support to resolve this issue. | Write, for Occupation only. | The Occupation lookup used for Employee writes returns two or more records with the same Description. | The duplicate record is dropped from that lookup, which marks the whole preload as failed. Sync stopped, zero employees processed. | Escalate. Support must identify and correct the duplicate Occupation record in Acumatica. |
Which Lookups Can Produce This
| Lookup | Read or write side | Key that must be unique |
|---|---|---|
| Union Local | Read | Union Local ID (Payroll Union Local ID) |
| Workers Compensation Code | Read | Workers Compensation Code (Work Code ID) |
| Occupation | Read | Position ID (the Occupation code) |
| Work Location | Write | Location code |
| Workers Compensation Code | Write | Description (first 50 characters) |
| Occupation | Write | Description |
Confirming the Error
- Open the sync execution in Sync History for the Acumatica connector.
- Find the step for the Employee entity, in the direction (read or write) seen.
- Check the Failures column for that entity row. A non-zero Failures count is the signature of this family: it means the run for that entity stopped before any employee records were processed.
- Open the errors list for that entity row. Match on the fixed part of the sentence, "encountered a duplicate" and "Contact support to resolve this issue," rather than on the lookup name or key value in quotes, since those vary by incident.
- Important: the words "in the Employee Read Service" can appear in the message even when the failing sync direction is write. Work Location and Workers Compensation Code duplicates on the write side reuse the read-service wording because of a defect in the provider. Confirm the actual direction from the Sync History step itself, not from the message wording.
- Read the preload progress entries in the Information list for the same step, just before the duplicate message, to see which lookup was in flight (for example, an entry naming Occupations or Union Local data) and confirm which lookup and key are implicated.
- Record the exact lookup type name (for example, Occupation or Workers Compensation Code) and the duplicate key value quoted in the message. Both are needed when escalating.
Resolving the Error
Failures on Preload
- This message alone does not identify the cause. Look in the same step's message list for one of the two duplicate-key messages above and follow that fix instead.
Duplicate Lookup Key (Employee Read Service and Employee Write Service Messages)
- The correction happens in Acumatica, on the record type named in the message: Union Local, Workers Compensation Code, Occupation, or Work Location.
- Escalate to support with the lookup type, the duplicate key value, the direction (read or write), and the sync execution id. Resolving the duplicate in Acumatica requires confirming which of the two conflicting records is correct, and whether the other should be renamed, merged, or deactivated.
- Do not attempt to edit the Acumatica record yourself to resolve this family. The field that must be unique differs by lookup: it is a short code for Union Local, Workers Compensation Code reads, and Work Location, but it is the record's Description for Occupation and for Workers Compensation Code on writes. An incorrect edit can create a new rejection instead of fixing the existing one.
- Once the duplicate is corrected in Acumatica, you or a support engineer can re-run the sync for the Employee entity in the affected direction.
- Confirm the fix worked: the Failures column for the Employee entity should now read zero, and the Added, Updated, or Unchanged counts should reflect the expected employee volume.
When to Escalate
If any of the following occur, you may need to reach out to Arcoro support for additional assistance.
- Any time either duplicate-key message appears. The message itself instructs to contact support, and the fix requires correcting source data in Acumatica together with confirming which record is authoritative.
- When "Failures on Preload" appears without an accompanying duplicate-key message for Occupation, Union Local, Workers Compensation Code, or Work Location. This points to a different Employee preload failure, such as Countries, Pay Rate Types, Pay Schedules, Employee Organizational Classes, Payroll Employee Classes, or Deduction Codes, which is outside this article and needs engineering review.
- When the Failures column is non-zero for the Employee entity but no message in the step's log clearly shows a duplicate-key sentence. Escalate with the sync execution id so engineering can pull the full preload log.