Why We Migrate V14 → V16 via V15 (Two-Hop Approach)
Frappe Framework
V14 → V16
Migration Guide
Challenges | Precautions | Post-Live Fixes | Full Checklist | Timeline
Prepared by: Infrastructure / Frappe DevOps Team
Date: June 2026 | Document Version: 2.0
A common question when planning a Frappe major version upgrade is whether a v14 database backup can be restored directly to a v16 bench and migrated in one shot. Technically, bench migrate will run all pending v15 and v16 patches in sequence — so it is possible. But in practice, skipping v15 significantly increases migration risk, and for production systems it is strongly discouraged.
What the Frappe Community Says (discuss.frappe.io, June 2026)
"Technically I would say yes. bench migrate runs all pending patches in order, so v15 and v16 patches
will all get applied after the restore. That said, I'd always recommend upgrading one major version at
a time. Skipping versions increases the chance of a patch failing mid-way, and if you have custom apps
or client/server scripts, the odds of something breaking are high. Best bet: try it on a test site
first before touching production." — marc_centura, Frappe Forum
Risks of Direct V14 → V16 Skip
v15 introduced intermediate schema changes (column additions, renames, data migrations) that v16 patches assume are already in place — skipping them causes patch failures mid-migrate
Custom apps built on v14 APIs may have two layers of breaking changes to handle simultaneously, making it very hard to isolate the root cause of failures
If bench migrate aborts mid-way in a direct skip, the database is in an ambiguous partial-v15/partial-v16 state that is difficult to recover without a full restore
v15 compatibility of custom apps can be tested independently before adding v16 complexity — two smaller problems are easier than one large one
Rollback from a partial v16 migrate is more complex than rolling back from a clean v15 state
Our Recommended Approach: V14 → V15 → V16 via Intermediate Hop
Step
What Happens
Step 1: V14 → V15
Set up v15 bench, restore v14 DB, run bench migrate (applies v15 patches only). Test on v15. Fix custom apps for v15 compatibility.
Step 2: V15 → V16
Take backup of validated v15 state, set up v16 bench, restore, run bench migrate (applies v16 patches only). Test on v16. Deploy to production.
Environment Strategy Overview
ENVIRONMENT 1 — V14 Production Bench : Current live system. Read-only during migration.
ENVIRONMENT 2 — V15 Staging Bench (Test) : New server. Validates v14→v15 hop. Used for v15 UAT.
ENVIRONMENT 3 — V16 Staging Bench (Test) : New server. Validates v15→v16 hop. Used for v16 UAT.
PRODUCTION CUTOVER : V16 bench replaces v14 production using validated runbook.