[x-license] Improve v9 license key version mismatch error guidance by aemartos · Pull Request #22180 · mui/mui-x

aemartos · 2026-04-24T08:23:26Z

I have followed (at least) the PR section of the contributing guide.

Summary

Makes the v8 → v9 license key upgrade requirement more discoverable for existing customers, both in the console warning and across the docs. The trigger was #22173, where a customer upgraded to v9 and hit the watermark without realizing the key format had changed — the console message pointed them at the pricing page instead of the account page, and the docs mention was buried.

Changes

Console warning (`packages/x-license`)

Rewrote the License key version mismatch console warning to point existing customers to regenerate a key from their account (free, inherits expiration) instead of the pricing page.
Added a dev-only hint on the watermark: "Open the browser console for details."

Redirects

Added two new /r/x-* short links in docs/public/_redirects:

/r/x-license-account → https://mui.com/store/account/licenses/
/r/x-license-key-upgrade → How can I generate a v9 license key? (support article)

Docs

Extracted the v8 → v9 warning into a shared component at docs/src/modules/components/V9LicenseUpgradeWarning.js, styled to match the native :::warning callout.
Added the warning to the four v8 → v9 migration guides and licensing page

Captura de pantalla 2026-04-24 a las 13 16 36

Captura de pantalla 2026-04-24 a las 13 16 50

code-infra-dashboard · 2026-04-24T08:27:39Z

Bundle size

Bundle	Parsed size	Gzip size
@mui/x-data-grid	0B^(0.00%)	0B^(0.00%)
@mui/x-data-grid-pro	🔺+274B^(+0.05%)	🔺+120B^(+0.08%)
@mui/x-data-grid-premium	🔺+274B^(+0.04%)	🔺+107B^(+0.05%)
@mui/x-charts	0B^(0.00%)	0B^(0.00%)
@mui/x-charts-pro	🔺+274B^(+0.05%)	🔺+119B^(+0.08%)
@mui/x-charts-premium	🔺+274B^(+0.05%)	🔺+126B^(+0.08%)
@mui/x-date-pickers	0B^(0.00%)	0B^(0.00%)
@mui/x-date-pickers-pro	🔺+274B^(+0.09%)	🔺+125B^(+0.16%)
@mui/x-tree-view	0B^(0.00%)	0B^(0.00%)
@mui/x-tree-view-pro	🔺+274B^(+0.23%)	🔺+129B^(+0.35%)

Details of bundle changes

Deploy preview

Check out the code infra dashboard for more information about this PR.

oliviertassinari · 2026-04-24T09:33:00Z


 # Migration from v8 to v9

+{{"component": "modules/components/V9LicenseUpgradeWarning.js"}}


I think we need to move this lower in the migration pages, for Pro and Premium users only.

Why: This currently gives the feeling to open source users that >50% of the users are paid, no, we are trying to make all the money from <10% of the users, so it's secondary, so it has to be lower.

michelengelen

LGTM ... the comment from @oliviertassinari is a valid concern. Could you adjust this before merge please?

oliviertassinari · 2026-04-24T09:38:27Z

@@ -1,5 +1,7 @@
 # Licensing

+{{"component": "modules/components/V9LicenseUpgradeWarning.js"}}


The description was designed to be right after the h1, to move after it, from a design perspective.

I was expecting docs-infra to break when this is not done, but surprisingly, it's resilient to it. So I think we need to update docs-infra to break in this case. cc @dav-is for awareness.

To be fair, I think we never tried this, I don't remember this ever been an issue. Let's move it for now under the description.

mnajdova · 2026-04-24T09:58:57Z

@@ -1,5 +1,7 @@
 # Licensing

+{{"component": "modules/components/V9LicenseUpgradeWarning.js"}}


To be fair, I think we never tried this, I don't remember this ever been an issue. Let's move it for now under the description.

mnajdova · 2026-04-24T10:01:34Z

    '',
-    'The license key you are using is not compatible with the version of the MUI X packages installed.',
-    'This happens when using a license key from a previous major version (e.g. a v8 license with v9 packages).',
+    'The license key you are using was issued for an older major version of MUI X (e.g. a v8 license with v9 packages installed).',


Suggested change

'The license key you are using was issued for an older major version of MUI X (e.g. a v8 license with v9 packages installed).',

// #npm-tag-reference

'The license key you are using was issued for an older major version of MUI X (e.g. a v8 license with v9 packages installed).',

This is needed so we don't forget to update the versions on the next major.

Can we do the opposite, parametrize the console to be specific?

aemartos · 2026-04-24T10:12:49Z

@oliviertassinari @mnajdova suggestions addressed.

I think we need to move this lower in the migration pages, for Pro and Premium users only.

@oliviertassinari there's no dedicated Pro/Premium section in these guides, so I placed it after ## Update @mui/material and @mui/system packages under a new explicit heading: "Update your license key (Pro and Premium)" after: "Update @mui/material and @mui/system packages"

The description has to be right after the h1, I believe, it breaks SEO metadata extraction otherwise, so there can't be an element here.
If it's indeed needed, and the page still build, docs infra will need to update the logic to crash the page.

Agreed that the docs-infra side (crashing the build when something sits between the H1 and <p class="description">) is worth doing, but I'd rather not bundle it here, this PR is scoped to the license migration guidance, and the infra change will likely touch a different area with its own review surface. Happy to open a follow-up issue for it.
cc @Janpot for awareness on the docs-infra side.

LukasTy

Nice improvement. 👍

LukasTy · 2026-04-24T10:51:46Z

+            from your <a href="https://mui.com/r/x-license-account/">MUI Store account</a>. The new
+            v9 key inherits the same expiration date as your existing v8 key, so there&apos;s no
+            extra cost during your current term. See{' '}
+            <a href="https://mui.com/r/x-license-key-upgrade/">


Nitpick, but shouldn't the link be relative?

Suggested change

<a href="https://mui.com/r/x-license-key-upgrade/">

<a href="/r/x-license-key-upgrade/">

It was correct. This should be a global link so it continues to redirect to the right place as we introduce changes to our billing infrastructure. It shouldn't be tied to an old version redirect rule because we don't want to have to update old versions redirect rules.

….com:aemartos/mui-x into aemartos/sto-127-enhance-v9-license-messages

aemartos self-assigned this Apr 24, 2026

aemartos added scope: x-license Changes related to @mui/x-license. type: enhancement It’s an improvement, but we can’t make up our mind whether it's a bug fix or a new feature. labels Apr 24, 2026

[x-license] improve v9 license key version mismatch error guidance

9f5c912

aemartos force-pushed the aemartos/sto-127-enhance-v9-license-messages branch from 06d4da7 to 9f5c912 Compare April 24, 2026 08:42

[docs] add v9 license upgrade warning to migration guides

8434b04

aemartos requested review from michelengelen and oliviertassinari April 24, 2026 08:55

oliviertassinari reviewed Apr 24, 2026

View reviewed changes

michelengelen approved these changes Apr 24, 2026

View reviewed changes

oliviertassinari changed the title ~~[x-license] improve v9 license key version mismatch error guidance~~ [x-license] Improve v9 license key version mismatch error guidance Apr 24, 2026

oliviertassinari reviewed Apr 24, 2026

View reviewed changes

mnajdova reviewed Apr 24, 2026

View reviewed changes

[docs] address PR review feedback

e1914b0

aemartos requested review from mnajdova and oliviertassinari April 24, 2026 10:13

LukasTy approved these changes Apr 24, 2026

View reviewed changes

[docs] use relative links in V9LicenseUpgradeWarning

f1ae113

aemartos force-pushed the aemartos/sto-127-enhance-v9-license-messages branch from 29fac4b to f1ae113 Compare April 24, 2026 11:06

aemartos and others added 4 commits April 24, 2026 14:47

Merge branch 'master' into aemartos/sto-127-enhance-v9-license-messages

ee05ecf

[license] parametrize version mismatch error with packageMajorVersion

b5d2c46

Merge branch 'aemartos/sto-127-enhance-v9-license-messages' of github…

f5a01da

….com:aemartos/mui-x into aemartos/sto-127-enhance-v9-license-messages

[docs] revert V9LicenseUpgradeWarning links to absolute URLs

f5924dd


		# Migration from v8 to v9

		{{"component": "modules/components/V9LicenseUpgradeWarning.js"}}

		@@ -1,5 +1,7 @@
		# Licensing

		{{"component": "modules/components/V9LicenseUpgradeWarning.js"}}

	'The license key you are using was issued for an older major version of MUI X (e.g. a v8 license with v9 packages installed).',
	// #npm-tag-reference
	'The license key you are using was issued for an older major version of MUI X (e.g. a v8 license with v9 packages installed).',

	<a href="https://mui.com/r/x-license-key-upgrade/">
	<a href="/r/x-license-key-upgrade/">

Uh oh!

Conversation

aemartos commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Console warning (packages/x-license)

Redirects

Docs

Uh oh!

code-infra-dashboard Bot commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle size

Deploy preview

Uh oh!

oliviertassinari Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

michelengelen left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oliviertassinari Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mnajdova Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

mnajdova Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

mnajdova Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

mnajdova Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

oliviertassinari Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aemartos Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

aemartos commented Apr 24, 2026

Uh oh!

LukasTy left a comment

Choose a reason for hiding this comment

Uh oh!

LukasTy Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

oliviertassinari Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aemartos Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

aemartos commented Apr 24, 2026 •

edited

Loading

Console warning (`packages/x-license`)

code-infra-dashboard Bot commented Apr 24, 2026 •

edited

Loading

oliviertassinari Apr 24, 2026 •

edited

Loading

michelengelen left a comment •

edited

Loading

oliviertassinari Apr 24, 2026 •

edited

Loading

oliviertassinari Apr 24, 2026 •

edited

Loading

oliviertassinari Apr 24, 2026 •

edited

Loading