Common Migration Failures
Parent: MongoDB Migration Patterns · Published reference · snapshot 2026-10-23 · skill mongodb-cohort-f1ebe93a2c8b
↓ Facts as markdownall context files
Source-anchored research for Common Migration Failures. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
How it works
- For oplog-dependent initial sync and CDC workflows, size source retention to preserve the history each workflow still needs: MongoDB says a logical initial sync restarts if it finds an oplog gap during oplog application and requires a window covering those apply phases; Percona ClusterSync, which uses change streams, says sync fails when needed source oplog operations expire before processing; AWS DMS says its task fails if oplog records expire before DMS reads them. (high confidence) (verified as of 2026-10-23) [source]
- AWS DMS documents MongoDB data-shape constraints that can block or narrow a migration: table mode requires consistent types for each field and does not replicate fields absent from target columns; its homogeneous MongoDB-compatible flow does not support inconsistent _id types or time-series collection migration. (medium confidence) (verified as of 2026-10-23) [source]
Problems, failure modes and limitations
- A MongoDB logical initial sync used to seed a destination can restart if oplog entries needed during clone and apply no longer fit within the source oplog window; the target also needs disk for the oplog buffer. MongoDB documents these restart conditions, and a production case report describes sync failure and disk exhaustion under high oplog generation. (high confidence) [source]
- Relational-to-MongoDB document construction can fail when legacy records contain null or missing values, failed numeric conversions, or incomplete relationships; a value with the expected shape can still be factually wrong. MongoDB schema validation enforces configured field types and ranges, but shape validation alone cannot establish historical truth. (medium confidence) [source]
- A MongoDB change-stream consumer used for migration CDC cannot resume from a token whose event has fallen out of the participating oplog; MongoDB reports ChangeStreamHistoryLost for that condition. A cross-cloud migration case report describes monitoring resume-token health and lag, disk use, and source-to-delta document counts while bulk copy and change capture ran together. (medium confidence) [source]
- Network interruption handling differs by tool: MongoDB native initial sync may resume after temporary network errors, but persistent errors restart it from the beginning; Percona ClusterSync documents that its initial sync is non-resumable and restarts from scratch after failure. (medium confidence) (verified as of 2026-10-23) [source]
- MongoDB documents a rare mongosync embedded-verifier false positive: differing document field order across source nodes can make verification fail even when mongosync copied the documents correctly. (low confidence) (verified as of 2026-10-23) [source]
Facts and statements
- Verification needs to match the workload and collection features: MongoDB says document-count comparison only verifies successful sync for insert-only workloads, while the embedded verifier skips capped, TTL-indexed, and non-default-collation collections; MongoDB also describes checks across documents, views, and indexes. (high confidence) (verified as of 2026-10-23) [source]
- Percona ClusterSync requires the same major MongoDB version on source and target and does not synchronize users, roles, or system.* collections; a migration that assumes full-cluster copying must provision this state separately. (low confidence) (verified as of 2026-09-08) [source]
Children
- No children recorded.