A migration is a bulk write into your general ledger, so before you run one it’s worth knowing what happens when things go wrong. This page answers that: which failures the system recovers from on its own, which ones you re-run, what you can and cannot undo, and how to trial the whole thing before it touches your real books.
A migration stages everything before it posts, keys every staged record to its source record, and surfaces failures as records you can retry rather than as partial writes you have to unpick.
What recovers without you
Several classes of failure are handled automatically. Knowing which ones saves you from intervening in a run that is already fixing itself.
- A stalled sync. A running sync reports a heartbeat every few minutes. Two missed heartbeats, roughly 6 minutes of silence, and the migration is treated as abandoned: its state is reset and the sync restarts from where it stopped.
- An interrupted sync. A run cut short by a worker shutting down mid-sync is picked back up once the connection is confirmed connected and idle.
- Transient errors on a single record. A unit of work that hits a temporary conflict retries on a backoff of roughly 15, 30, 60, 120, and 240 seconds. A failure that looks like a database hiccup rather than a data problem keeps retrying on a longer cadence, because those resolve on their own.
- A stuck connection. A migration still syncing, interrupted, or waiting to be mapped after about a day is cleared back to a synced state by a safety sweep, so it cannot sit stuck indefinitely.
- An abandoned lock. Only one sync runs per company connection at a time. That exclusivity expires after about 3 hours, so a crashed run cannot block future syncs permanently.
None of these require a support ticket. Check the sync history from the migration’s ⋮ menu before concluding a run is dead.
What you re-run
The rest surfaces as records on the Error tab of the Data Sync step, each with a message naming its cause.
Re-running is safe. Every staged record is keyed to its source record ID, and the staging row remembers which DualEntry record it created. A retry updates or completes that same record rather than creating a second one, which is why fixing a mapping and retrying 100 failed transactions does not produce 100 duplicates.
The usual sequence is: read one error message, fix the underlying mapping or configuration, then select the affected rows and use the bulk Retry action. One fix normally clears most of a batch, because the same mapping gap produces every failure in it. Bulk actions on the Data Sync step also cover skip, unskip, create from draft, deactivate, activate, replace, archive, and export to CSV, so you can work a large error set without opening records one at a time.
Where the automatic mapping picked the wrong DualEntry record type, open the row and rebuild it in the transaction builder, choosing the correct type from bill, invoice, direct expense, bank transfer, cash sale, customer or vendor payments, credits, prepayments, prepayment applications, refunds, journal entry, or intercompany journal entry.
What you can undo, and what you cannot
Undo is bounded by normal accounting immutability rather than by the migration.
You can skip a staged record so it never posts, deactivate a mapped account or classification, unassign a mapping, archive a migrated transaction, and disconnect the source entirely. Skipping or deactivating a record applies to every source record mapped to the same target, so a shared account cannot end up half-active.
You cannot delete a posted transaction. DualEntry archives rather than deletes accounting records, and archiving is blocked where it would break integrity: a record matched against a bank transaction or included in a completed reconciliation stays. Unassigning a mapping can optionally archive its target, and that archiving is blocked when the target falls in a locked period or is otherwise immutable. You get a message explaining why rather than a silent failure.
There is no single action that reverses a completed migration. Undoing one means archiving the migrated records, which is bounded by period locks and reconciliation state. This is the reason to trial a migration in a sandbox first rather than to treat the first run as reversible.
How to trial a migration first
Trial runs happen in a sandbox organization rather than in your production books. A sandbox is a separate organization with its own data, and it carries an expiry date after which it is archived automatically, so a trial cannot linger and be mistaken for the real thing.
Running the migration into a sandbox first gives you three things worth the extra day: a rehearsal of the mapping decisions, a realistic sense of how many records land in Error and why, and a tie-out you can practice before it matters. The mapping work is the part that benefits most, because the second pass is much faster than the first.
The hands-off One-Click path, which auto-creates matching accounts and companies, auto-skips accounts with no transaction history, and advances into Data Sync on its own, is available only to organizations that started from a migrated sandbox. That restriction is enforced server-side: an organization that is not a migrated sandbox is treated as manual regardless of what was requested. Everyone else maps by hand, which is the path this documentation describes throughout.
Ask your DualEntry contact to provision a migration sandbox if you want a dry run. It is the standard answer to “can we see this work on our data first”.
Common questions
These are the questions that come up before a first migration, answered against how the system actually behaves rather than in principle.
Can the migration be run more than once? Yes. Staged records are keyed to their source record, so a second sync updates what it already created rather than duplicating it. Scheduled connections also re-sync on their own interval once connected.
Can I stop a migration that is running? Yes. Pause it from the migration view while it is running or waiting to be mapped. Pausing stops the schedule and keeps the work already done.
What happens if I disconnect the source? Disconnecting removes the replication connector, revokes the source system grant, and deletes the stored credentials. Records already imported into your ledger stay; they are ordinary DualEntry records at that point. See data handling during a migration.
Does a failed record post partially? No. A record either becomes a DualEntry transaction or sits on the Error tab. Where a source document cannot be reconstructed within tolerance, the record fails rather than posting an implausible balancing figure.
Will I be told when a sync finishes? Usually not, and never on failure. The outcome email is sent on success only, at most once for the life of an integration, and only where three things hold: the organization started as a migrated sandbox, the sync was triggered manually or run for a specific date range, and no outcome email has been sent for that integration before. The initial sync, background re-syncs, and record imports never send it, and a failed sync never sends it. Watch the sync history drawer rather than your inbox.
Is there a record of what the migration did? Yes. The migration’s Activity view holds its audit log, migration status changes are written to the audit trail, and the Data Sync step keeps a per-record link between each source record and the DualEntry record it produced.
