Migration Debt
A planned migration starts well but stalls mid-execution, leaving the system permanently split across old and new states.
- Also known as
the half-migrated systemthe permanent transition statestranded migrationthe never-finished move
- First noticed by
staff engineerarchitectdelivery lead
- Mistaken for
- work in progress
- Often mistaken as
- acceptable technical debt
Why it looks healthy
Concrete external tells that make the pattern read as responsible behavior.
- Phase one shipped on time
- The new system is visibly in production
- The old system is in "legacy" mode
- Leadership already celebrated the milestone
Definition
What it is
Blast radius code operations delivery team
A migration - to a new platform, database, cloud environment, or architecture - begins but never completes, creating an indefinite dual-state system.
How it unfolds
The arc of the pattern
-
Starts
A migration is planned, resourced, and begins with enthusiasm.
-
Feels reasonable because
The first phase is successful and the team moves on to other priorities.
-
Escalates
New features are built on both old and new systems. The old system receives patches. Completion keeps getting deprioritized.
-
Ends
Years later, the system has two data stores, two deployment models, or two infrastructure patterns - and nobody is sure how to finish.
Recognition
Warning signs by stage
Observable signals as the pattern progresses.
EARLY
Early
- Migration has no explicit completion criteria.
- No one owns the migration end state.
- New features begin before old ones are migrated.
MID
Mid
- Both old and new systems receive production traffic.
- Migration progress is not tracked publicly.
- The team cannot describe what remains to be migrated.
LATE
Late
- The migration has been in progress for over a year.
- New engineers learn both systems as permanent.
- The completion is described as a future initiative rather than a current one.
Root causes
Why it happens
- Completion criteria were not defined before starting
- Business priorities shift mid-migration
- The migration is harder than expected
- No one owns the end state formally
Response
What to do
Immediate triage first, then structural fixes.
First move
Pick a retirement date for the old system, write it down, and put one specific owner on closing the gap to it.
Hard trade-off
Accept sunk cost on parts of the new system that will not be worth finishing, or accept operating both systems forever.
Recovery trap
Launching "phase three" to unblock phase two, which converts unfinished migration into a multi-phase program with no ending.
Immediate actions
- Define what done looks like before the next phase begins
- Freeze new development on the old system
- Assign a named migration owner with authority to prioritize completion
Structural fixes
- Track migration completion as a first-class metric
- Set a retirement date for the old system before the new one is built
- Treat dual-state as a temporary and expensive condition
What not to do
- Do not accept indefinite dual-state as a stable operating condition
- Do not start a migration without a named owner and completion criteria
AI impact
How AI distorts this pattern
Where AI-assisted workflows accelerate, hide, or help with this failure mode.
AI can help with
- AI can help map what remains to be migrated, identify dependencies on the old system, and generate migration scripts for remaining cases.
AI can make worse by
- AI can make working with both old and new systems easier, reducing the pain that would otherwise force completion of the migration.
Relationships
Connected patterns
Causal flows inside Failure Modes, and related entries across the site.
Easy to confuse with
Nearby patterns and how this one differs.
-
Friendly rewrite never defined an endpoint. Migration debt defined one and then stopped walking toward it.
-
Dependency fog is unclear ownership of commitments. Migration debt is clear ownership of a migration that is not finishing.
- Adjacent concept Acceptable technical debt
Debt with a plan and a date is managed. Migration debt is a permanent fork pretending to be a stage.
Heard in the wild
What it sounds like
The phrase that signals the pattern is about to start, and who tends to say it.
We're still in the middle of the migration to the new system.
Said byany engineer when asked about the current architecture
Notes from practice
What experienced people notice
Annotations from engineers who have worked this pattern before.
- Best momentWhen intervention actually changes the trajectory.
- When a migration has no defined completion criteria or owner
- Counter moveThe specific action that breaks the pattern.
- A migration without a retirement date is not a migration, it is a permanent fork.
- False positiveWhen this pattern is actually the correct call.
- Long migrations are sometimes genuinely complex. The failure mode is indefinite dual-state without a plan to end it.