Knowing what changed in Mendix 11 is one thing; executing the upgrade safely is another. This playbook is the practical companion to our What’s New in Mendix 11 guide – a phase-by-phase plan for moving an app from Mendix 9 or 10 to the 11.12 Long-Term Support (LTS) release without nasty surprises. Work through it in order; each phase ends with a checkpoint you should be able to tick before moving on.
Who this is for
Teams running production apps on Mendix 9 or 10 that need to plan a move to 11 LTS – and want a repeatable process rather than a leap of faith. If you own one app, this is your project plan. If you own a portfolio, run it once as a pilot, capture what you learn, then template it for the rest.
The golden rule: step through the LTS releases
Mendix supports three major versions at once, so there is no need to rush – but there is a right path. Do not jump straight from 9 to 11. Step through the Long-Term Support releases in order: 9.24 LTS → 10.24 LTS → 11.12 LTS. Each hop is smaller, each intermediate state is supported and testable, and problems surface one manageable layer at a time instead of all at once. Treat each hop as its own mini-project with its own test cycle.
Phase 1 – Assess: take inventory before you touch anything
You cannot plan an upgrade you have not measured. Before changing a single version number, build a picture of what the app actually depends on:
- Marketplace modules and widgets – list every one, its version, and whether a Mendix 11-compatible release exists. Unmaintained or abandoned modules are the single most common source of upgrade pain.
- Custom and Dojo widgets – identify anything built on the legacy Dojo client. The React client is the default in Mendix 11 and Dojo is deprecated (slated for removal in Mendix 12), so Dojo widgets need a migration plan.
- Java version and custom Java – Mendix 11 requires Java 21 (Mendix 10 already forced this at 10.21). Note any custom Java actions and dependencies that may need updating.
- Deprecated API usage – flag calls to APIs deprecated in 10 or removed in 11 so they are on the list, not a surprise at build time.
- Version control – confirm the app is on Git. SVN is fully retired in Mendix 11; any app still on SVN must migrate to Git first.
- Legacy file documents – very old apps carrying pre-Mendix-5.12 file documents will not start on 11 and need remediation.
Checkpoint: you have a written inventory of modules, widgets, Java dependencies, and known blockers, each marked ready / needs-work / blocker.
Phase 2 – Plan: the decisions that shape the upgrade
The inventory turns into a plan by making a few decisions up front:
- The React client migration. This is the biggest architectural change. Decide, per widget, whether to replace a Dojo widget with a React equivalent, rebuild it, or drop it. Plan UI regression time – this is where it goes.
- Runtime breaking changes. Put the known behavioural changes on the plan: entity access is enforced on the home-page microflow (ShowHomePage now requires explicit security), XPath math operators must be explicitly enabled, and some deprecated Java APIs were removed. Each needs a small, specific fix.
- Sequencing. Decide the order of the hops and who owns each. Lock a code freeze window for each hop so you are not upgrading a moving target.
- Environments. Plan to do the work on a branch, deploy to a non-production environment first, and keep the current production version deployable throughout.
Checkpoint: a sequenced plan with a widget-by-widget React decision, a list of breaking-change fixes, owners, and a code-freeze window per hop.
Phase 3 – Migrate: make the move, version by version
Now execute, one hop at a time:
- Bump to the next LTS (e.g. 9.x → 9.24, then open in 10.24), and let Studio Pro surface consistency errors. Resolve them before moving on – do not carry errors forward into the next hop.
- Update modules and widgets to their compatible versions as you go; replace or rebuild the ones flagged in Phase 1.
- Apply the breaking-change fixes from your plan – security on ShowHomePage, XPath operator settings, Java updates – and get to a clean build at each hop.
- Commit small and often with clear messages, so a bad change is easy to isolate and undo.
Checkpoint: the app builds clean on 11.12 with zero consistency errors and every module on a supported version.
Phase 4 – Test and harden
A clean build is not a working app. Test deliberately:
- Functional regression across the critical paths – the flows that would hurt most if they broke.
- UI regression on the new React client – this is the highest-risk area, so give it real attention across browsers and devices.
- Performance – compare key pages and microflows against a baseline you captured before the upgrade, so you can prove you did not regress.
- Security – re-verify access rules, especially anywhere the enforced entity-access changes touched, and run a security overview.
Checkpoint: regression, UI, performance, and security all signed off against a pre-upgrade baseline.
Phase 5 – Cut over, with a rollback ready
Deploy with a way back:
- Schedule the cutover and communicate it. Mendix 11 supports zero-downtime deployments, but plan the window anyway.
- Keep the previous version deployable and take a database backup immediately before cutover, so rollback is a known, tested step – not an improvisation.
- Monitor closely for the first hours and days: errors, performance, and the specific areas you changed.
- Only then decommission the old version, once you are confident the new one is stable.
Checkpoint: live on 11.12 LTS, monitored, with a rollback path you have actually validated.
What trips teams up
- Skipping the LTS hops and jumping 9 → 11 – everything breaks at once and nothing is isolable.
- Discovering an abandoned Marketplace module late – find it in Phase 1, not at build time.
- Underestimating the React UI migration – it is the biggest change and the biggest test effort; budget for it.
- Treating it as one big bang instead of a sequence of small, tested steps with a code freeze.
- No baseline – without pre-upgrade performance and behaviour captured, you cannot prove you did not regress.
The pre-flight checklist
- App is on Git (not SVN).
- Every Marketplace module has a confirmed 11-compatible version – or a replacement plan.
- Dojo/custom widgets have a per-widget React decision.
- Java 21 confirmed; custom Java reviewed.
- Breaking-change fixes listed (ShowHomePage security, XPath operators, removed APIs, legacy file documents).
- Pre-upgrade performance and behaviour baseline captured.
- Non-production environment ready; rollback path and backup plan defined.
- Code-freeze window agreed for each hop.
How Golden Earth runs an upgrade
This is work we do often, and we run it exactly as above – senior engineers only, documentation-first, embedded in your team. That means the assessment is honest, the plan is realistic, the risky changes get senior review, and you own the knowledge at the end rather than a black box. If you want a second pair of experienced hands on an upgrade – or someone to run it end to end – talk to an expert.