Dual-write sync errors

Dual-write errors have a shape: a specific message on one side of the integration, a cause on the other, and a fix that is almost always about setup order, reference data, or the application user rather than about the map itself. This reference lists the messages that recur, where each appears, and what to do. The diagnostic method — reference data before transactions, one map at a time — is in dual-write troubleshooting patterns; the architecture in Dynamics 365 dual-write integration.

Where to look

• Initial sync: in Finance and Operations, Data management > Dual-write > select the map > Execution details. Each run shows rows processed and rows failed with the error per row.
• Live sync, F&O to Dataverse: the Dual-write errors table in Dataverse (Integration Errors view in the Dual-write admin experience), plus the Dataverse async operation log for plug-in failures on the receiving table.
• Live sync, Dataverse to F&O: the F&O side logs the failed write against the business event / integration log; the Dataverse row keeps a sync status.
• Map state: Dual-write page in F&O or the Dual-write admin app in Dataverse — Running, Not running, Paused, and the error count.

Setup and dependency errors

"Referenced record not found" / "Lookup value for field X could not be resolved" / "Could not find target row"

Symptom. Customer, product, or order rows fail in initial or live sync naming a lookup field.

Cause. The referenced row — currency, unit of measure, customer group, payment terms, site, warehouse, sales tax group — does not exist in the target because its map has not run, or ran with a filter that excluded it. Dual-write does not create references on the fly.

Fix. Run the reference-data maps first in the documented dependency order (legal entities and companies, then currencies, units, countries and other reference tables, then parties, customers, vendors, products, then transactions). Re-run the failing map.

Prevention. Initial sync one map at a time, verifying each is clean before the next, and never run a transactional map before its references.

"Company X does not exist in Dataverse" / "cdm_company not found" / the company lookup is empty

Symptom. Everything fails for one legal entity.

Cause. The Company (cdm_company) map has not run for that legal entity, or a row was created in Dataverse without a company value. Nearly every dual-write table carries a company lookup.

Fix. Run the Companies map first; on Dataverse forms for synced tables, default the company field and make it required with a business rule.

"Integration key" / "An item with the same key has already been added" / alternate key violation 0x80040237

Symptom. Rows fail with duplicate-key messages, or duplicates appear on one side.

Cause. The same business record exists on both sides from earlier manual entry or a previous integration, with keys that do not match the map's integration key. Dual-write cannot decide they are the same record.

Fix. Decide the master per table, align keys with a one-off data fix (update the Dataverse alternate key values to match F&O's, or vice versa), delete the orphaned duplicates, then re-run initial sync for that map.

Prevention. Clean both sides before the first sync; Dataverse alternate keys covers how the keys work.

Number sequences: rows created in Dataverse fail in F&O with a blank or rejected number

Cause. A record created on the Dataverse side arrives in F&O without an F&O-generated number, and the F&O number sequence for that record type is not configured for the way the map supplies the key (manual entry not allowed, or the Dataverse autonumber not set up).

Fix. Follow Microsoft's per-entity guidance on number sequences for dual-write — typically configuring the number sequence to accept the value the map provides, or generating the number in Dataverse with an autonumber column that matches the F&O format.

Validation errors

"Validation failed" / "Field X must be filled in" / "Cannot edit a record in Table (Y). Field Z must be filled in."

Symptom. Live sync writes fail with F&O or Dataverse field validation messages.

Cause. The target enforces a mandatory field the source did not supply — business-required columns in Dataverse, mandatory fields on the F&O entity, or a value F&O's validation rejects (an address without a country, a customer group not in the target company). Legacy data that F&O tolerated in place fails when it is re-validated on the way out.

Fix. Read the field named. Either map a source for it, set a default in the map (the transform column), or cleanse the source data. For F&O data quality, filter the map to exclude offending rows until they are fixed.

Prevention. Validate mandatory fields on both sides before enabling a map; align required-field rules across the two systems.

"The record is being modified by another process" / concurrency and conflict errors

Cause. Both sides changed the same row within the sync window, or a plug-in or flow on the Dataverse side updates the row dual-write just wrote, which loops back.

Fix. Check the conflict resolution setting on the map; find plug-ins and flows on the synced table that write to it and exclude dual-write's application user from their triggers (check the initiating user, or use a filtering attribute).

Prevention. Design plug-ins and flows on synced tables knowing dual-write writes to them — see master data services vs dual-write for the loop pattern.

"Value is not valid for option set" / choice mismatch

Cause. The map's value transformation between an F&O enum and a Dataverse choice is incomplete — a new enum value on one side without a matching choice on the other.

Fix. Add the value to the transform on the map and, if needed, the choice in Dataverse.

Security and application user

"Principal user is missing prvXxx privilege" — 0x80040220 / "Access denied" on the Dataverse side

Symptom. A map fails entirely, or fails for one table, with a privilege error.

Cause. The dual-write application user in Dataverse lacks the privilege. A custom table added to a map without updating the app user's role, a field-level security profile that excludes the app user, a new security role assignment that removed a needed one, or the app user disabled.

Fix. Check the application user's roles (the Dual-write app user roles Microsoft installs, plus a custom role for custom tables) and any field-level security profiles on the table; enable the user if disabled.

Prevention. Every custom table added to a map comes with a role change for the app user. Dataverse security model covers roles and profiles.

"The user is not a member of the organization" / 401 from Dataverse

Cause. The application user was removed from the environment, or the environment was copied and the app user was not recreated.

Fix. Recreate the application user for the dual-write app registration and assign roles; relink the environments if the copy broke the link.

Authorisation errors on the F&O side

Cause. The Dataverse-side integration identity is not registered in F&O's Microsoft Entra applications, or lacks the security role for the entities in the map.

Fix. Register the app in F&O under System administration > Microsoft Entra applications with an appropriate user and role.

Map state and schema

Map shows Not running / stops after errors

Symptom. Live sync silently stopped; the map's state is Not running.

Cause. Dual-write stops a map after a schema change on either side, after an environment refresh, upgrade, or F&O service update, or when the live-sync error threshold is hit.

Fix. Open the map, use Refresh tables (or Refresh entities) to pick up schema changes, review and resolve the logged errors, then Run. Maps do not restart themselves.

Prevention. Put "check dual-write map states" in the post-update checklist for every F&O service update and Dataverse solution deployment — One Version and updates covers the cadence.

"Field X does not exist in entity Y" / "Column not found" after adding a field

Cause. A field was added to the F&O entity or the Dataverse table and the map's cached schema is stale; or a custom field was added to a map but the entity extension was not deployed to this environment.

Fix. Refresh the map's schema, add the mapping, deploy the entity extension, restart.

Initial sync times out or stalls

Cause. Volume: a large table synced in one batch during a busy period competes with F&O batch jobs and the Dataverse async service.

Fix. Filter initial sync by legal entity, date range, or group and run batches in a quiet window; skip initial sync for maps whose data already matches and start live sync only.

Environment link errors: "Environments are not linked" / "The linked environment does not match"

Cause. An F&O environment was refreshed from another (production to sandbox), and the dual-write link now points at the wrong Dataverse environment, or vice versa.

Fix. Unlink and relink the correct pair from Lifecycle Services / the Power Platform admin centre; recreate the application user; refresh and restart maps. Never relink a sandbox to production Dataverse.

Prevention. A refresh checklist that includes dual-write relinking; Dynamics 365 Finance environments and LCS covers the refresh process.

Reading the pattern

If many maps fail at once, it is the application user, the environment link, or a company row. If one map fails for every row, it is a schema or reference-data problem. If a map fails for a few rows, it is data quality or a key conflict. If a map worked and then stopped, it is a schema change, an update, or an error threshold. Start with which of those four you have, and the specific message above will confirm it.