Legacy modernization rarely fails because the new technology is wrong. It fails because the old system contains knowledge nobody documented, and the programme treats that knowledge as a detail to discover later. The result is a rewrite that looks complete in a demo and breaks in the first month of real trading.
This troubleshooting guide is for the manager who has a legacy system that still works but cannot be changed safely. A legacy ERP, a desktop application built for one department or a set of linked spreadsheets all create the same problem: the business knows the output but not the rule. The guide covers the symptoms, the underlying causes, a diagnostic sequence and the fixes that reduce the risk of a cutover.
Symptoms worth taking seriously
- The big-bang cutover keeps slipping. Each new date is justified by another round of testing, not by a measurable reduction in risk.
- Dual running never ends. The old and new systems stay in parallel because nobody trusts the new one.
- Rules appear after migration. Staff say "the old system knew to do that" only after the new system does something different.
- Data quality surprises. Duplicate customers, orphaned orders and impossible dates surface during migration, not during discovery.
- Integration regressions. The new system works alone but breaks the accounting, warehouse or payment connection.
- Performance is worse. The rewrite is functionally close but slower because the original had years of tuning and shortcuts.
- Staff create workarounds. Spreadsheets reappear beside the new tool, which is a signal that the workflow does not fit.
- Costs rise without scope changes. The team is spending more time on discovery than delivery, and the contract has no mechanism to manage it.
What usually causes the failure
- No system of record map. Nobody has written down which system owns which field and which downstream report depends on it.
- Requirements written from screens. The team documents what the old interface looks like instead of the business rule behind it.
- No behavioural baseline. There is no test suite that captures current outputs, so "no regression" is an opinion.
- Migration treated as a file copy. Data migration is a business reconciliation exercise, not only an extract and load.
- Big-bang by default. The programme chooses one cutover because slices feel slower, without pricing the risk of a single failure.
- No business owner. The vendor owns the backlog and the business discovers the trade-offs at acceptance.
- The old team is not protected. The people who understand the legacy rules are pulled onto the new build and leave the old system unmaintained.
Diagnose before you rewrite another screen
- Baseline current behaviour. Capture the outputs that matter: invoices, stock movements, statements, reports and integrations. Save them as golden files for comparison.
- Map data ownership and dependencies. List every system, file, report and manual step that reads or writes the legacy data.
- Extract rules with examples. For each important calculation or exception, record the input, the rule, the output and a real example. Validate it with the person who handles the exception.
- Profile the data. Measure duplicates, missing keys, invalid values and records that no current process can explain.
- Build a test harness before the new build. If you cannot replay a month of transactions and compare outputs, you cannot prove the replacement is safe.
- Choose the first slice by risk and value. Pick a boundary with a clear owner, a measurable outcome and a rollback path.
- Rehearse the cutover and the rollback. Time both. A rollback plan that has never been executed is not a plan.
Fixes that work
Use a strangler pattern, not a cliff
Put a routing layer in front of the legacy system. Move one capability at a time to the new service, and send everything else to the old system. This lets the business keep trading while the replacement grows. The pattern is well documented and works for APIs, batch jobs and user interfaces.
Separate the data migration from the feature rewrite
Migrate the minimum data needed for the first slice, reconcile it, then repeat. Do not wait for a perfect historical dataset. Define which history must be searchable, which can be archived and which can be discarded under a retention policy.
Intercept events where the old system cannot be changed
If the legacy application has no usable API, capture changes at the database, file or message level and publish them to the new service. Treat this as a temporary bridge with monitoring, not a permanent architecture.
Run parallel only where the risk justifies it
Parallel running doubles operational work and creates reconciliation disputes. Use it for the first billing cycle or the highest-risk process, with a written exit condition. For lower-risk slices, a strong test harness and a rollback plan are usually enough.
Retire before you rebuild
List the features nobody uses and the reports nobody reads. Deleting them reduces scope and avoids rebuilding complexity that only exists because of history. Get the business owner to sign the retirement list.
Change the commercial model
Price discovery, slice delivery and run support separately. A fixed price for an unknown legacy system encourages optimistic estimates and expensive change requests. A capped discovery phase followed by slice-based delivery gives both sides a clearer basis for decisions.
Evidence checklist
- System and data dependency map. Owner: technical lead. Evidence: signed diagram with interfaces and owners.
- Business-rule register with examples. Owner: business analyst. Evidence: reviewed rules and test cases.
- Golden-output comparison for each slice. Owner: QA lead. Evidence: test report showing differences resolved.
- Data reconciliation report. Owner: finance or operations. Evidence: opening and closing balances agreed.
- Cutover and rollback runbook. Owner: programme manager. Evidence: rehearsal log with timings.
- Retirement list. Owner: business owner. Evidence: signed scope decision.
Metrics
- Percentage of business rules covered by an automated comparison test.
- Number of integration endpoints migrated and verified.
- Data reconciliation variance by account or process.
- Cutover rehearsal time against the agreed window.
- Incidents in the first 30 days after each slice, split by severity.
- Share of the legacy estate retired, not merely replaced.
If you need the dependency map, slice plan and test harness built before the rewrite, start with Custom Software & Integrations; the pricing page explains how we scope discovery, delivery and handover. For the interface layer, read the REST API design checklist.
Sources
- Martin Fowler, StranglerFigApplication, accessed 17 November 2026.
- Microsoft Azure Architecture Center, Strangler Fig pattern, accessed 17 November 2026.
- AWS Prescriptive Guidance, Strangler fig pattern, accessed 17 November 2026.
- NIST SP 800-64 Rev. 2, Security Considerations in the System Development Life Cycle, accessed 17 November 2026.
Responses (0)
No comments yet. Add the first one below.
Leave a response
Your email address will not be published. Required fields are marked *.