Dual-write troubleshooting patterns

Dual-write works, in the sense that once it is running cleanly it keeps customers, products, and orders aligned between Finance and Operations and Dataverse with very little attention. Getting it to run cleanly is the part that consumes weeks, and the same handful of failures account for most of that time. This guide is about those failures and the order in which to look for them. For what dual-write is and when to use it at all, start with Dynamics 365 dual-write integration and master data services vs dual-write.

First principle: reference data before transactional data

Almost every dual-write failure in a new environment is a reference-data failure wearing a transactional disguise. A customer map fails because the customer group does not exist in Dataverse. A sales order map fails because the currency, the unit of measure, or the site was never synced. Dual-write is strict about lookups: if the row a lookup points to has not been synced, the record fails.

Microsoft publishes the map dependency order. Follow it literally: legal entities and companies, then currencies, units, countries and other reference tables, then parties and customers and vendors, then products, then transactions. Run initial sync in that order, one map at a time for the first pass, and check each one is clean before starting the next. Running everything at once and then reading the error log is slower, not faster.

Initial sync failures

Initial sync stalls or fails for a small number of reasons.

Volume. Large tables time out. The fix is to sync in batches by filter (by legal entity, by date range, by customer group) rather than the whole table, and to run initial sync during a quiet window for F&O, since it competes with batch jobs.

Lookup gaps as above. The error message names the missing reference; go and sync that map first.

Data quality on the F&O side. Customers with blank mandatory fields, products without a default unit, records that would fail F&O's own validation if re-entered. Dual-write applies validation on write, and legacy data that F&O tolerated in place fails on the way out. Cleanse first or filter the map to exclude the offenders and deal with them separately.

Integration key conflicts. If the same customer exists in both systems from earlier manual entry and the keys do not match, initial sync either creates duplicates or fails on alternate-key violations. Decide which system is authoritative per table before the first sync, and align keys with a one-off data fix.

Live sync failures

Once live, failures surface in the dual-write error log and in the Dataverse integration error tables. The recurring ones:

Company context. F&O records belong to a legal entity; Dataverse rows carry a company lookup. A user creating an account in Dataverse without a company, or with the wrong one, fails the write to F&O. The fix is usually a default company on the Dataverse form and, in mixed landscapes, a business rule that makes it mandatory.

Ownership and security. The integration user needs rights on both sides. A new table added to a map, a new security role, or a field-level security profile on Dataverse can silently block writes. When a map that worked yesterday fails today, check permissions before anything else.

Field mappings after customisation. A new mandatory field on either side, added by a developer who did not know dual-write existed, fails every write until the map is updated with a default or a transformation. Dual-write map changes go through the same ALM as everything else; treat them as part of the release.

Concurrent edits. Both systems can write the same record within seconds, and dual-write is not a conflict resolver. Choose a system of record per table and enforce it with read-only forms or field security on the other side; see the master data services comparison for the reasoning.

Environment lifecycle. A refreshed sandbox, a restored Dataverse environment, or an F&O database movement breaks the link. Relinking and re-running initial sync for affected maps is part of any refresh runbook.

A diagnostic order that works

1. Is the environment link healthy? Check the dual-write admin page in Finance and Operations for the connection state before reading any error.
2. Is the map running? A stopped map fails silently from the user's perspective.
3. What does the error say, exactly? Dual-write errors are verbose and usually name the table and field. Read to the end.
4. Does the referenced lookup exist on the target side? If not, sync it.
5. Did anything change: a security role, a new field, a solution import, an F&O update? Correlate with the change calendar.
6. Reproduce with one record through the UI, with the integration user's permissions, and watch the error in real time.

Operational hygiene

Alert on the error tables rather than waiting for users. A small Power Automate flow that emails when the Dataverse integration error count rises is cheap. Review and clear the error log weekly; an error log with ten thousand stale entries hides the new ones. Keep a document of which maps are active, which are customised, and why. Version the map customisations with the solution.

Performance-wise, dual-write adds latency to saves on both sides because the write is synchronous. Users notice on tables with heavy maps. Keep maps lean, avoid mapping fields nobody uses, and test save times on the busiest forms with dual-write on.

What dual-write is not for

High-volume transactional data. Mapping every inventory transaction or every journal line through dual-write will hurt both systems. Use it for master data and the handful of documents that need to be visible on both sides, and use Synapse Link or an eventing pipeline for the rest.

Stability verdict

Stable once the reference-data foundation is right and the system-of-record rules are enforced. Unstable, and permanently noisy, when it is switched on over unclean data or asked to arbitrate between two systems that both think they own the customer.