Skip to content

[x-license] Improve v9 license key version mismatch error guidance #22180

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aemartos wants to merge 9 commits into
base: master
Choose a base branch
from
Open

[x-license] Improve v9 license key version mismatch error guidance #22180

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
9f5c912
[x-license] improve v9 license key version mismatch error guidance
aemartos Apr 24, 2026
8434b04
[docs] add v9 license upgrade warning to migration guides
aemartos Apr 24, 2026
e1914b0
[docs] address PR review feedback
aemartos Apr 24, 2026
f1ae113
[docs] use relative links in V9LicenseUpgradeWarning
aemartos Apr 24, 2026
ee05ecf
Merge branch 'master' into aemartos/sto-127-enhance-v9-license-messages
aemartos Apr 24, 2026
b5d2c46
[license] parametrize version mismatch error with packageMajorVersion
aemartos Apr 24, 2026
f5a01da
Merge branch 'aemartos/sto-127-enhance-v9-license-messages' of github…
aemartos Apr 24, 2026
f5924dd
[docs] revert V9LicenseUpgradeWarning links to absolute URLs
aemartos Apr 24, 2026
9671091
Merge branch 'master' into aemartos/sto-127-enhance-v9-license-messages
aemartos Apr 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 2 additions & 8 deletions docs/data/introduction/licensing/licensing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Licensing

{{"component": "modules/components/V9LicenseUpgradeWarning.js"}}
Copy link
Copy Markdown
Member

@oliviertassinari oliviertassinari Apr 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member

@mnajdova mnajdova Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


<p class="description">MUI X is an open-core, MIT-licensed library. Purchase a commercial license for advanced features and support.</p>

## MIT vs. commercial licenses
Expand Down Expand Up @@ -124,14 +126,6 @@ This is [the relevant clause in the EULA.](https://mui.com/legal/mui-x-eula/#req
When you purchase a commercial license, you'll receive a license key by email.
This key removes all watermarks and console warnings.

:::warning
If you're upgrading from v8 to v9, you'll need to generate a new license key from your [MUI Store account](https://mui.com/store/account/orders/).
The new v9 key will have the same expiration date as your existing v8 key.

Upon renewal, you'll need to choose which license key to renew.
Note that renewing a v9 license key is priced differently from a v8 renewal.
:::

:::warning
Orders placed after **May 13, 2022** come with a license key by default that is only compatible with MUI X from `v5.11.0` and upwards.

Expand Down
2 changes: 2 additions & 0 deletions docs/data/migration/migration-charts-v8/migration-charts-v8.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ productId: x-charts

# Migration from v8 to v9

{{"component": "modules/components/V9LicenseUpgradeWarning.js"}}
Copy link
Copy Markdown
Member

@oliviertassinari oliviertassinari Apr 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


<p class="description">This guide describes the changes needed to migrate Charts from v8 to v9.</p>

## Introduction
Expand Down
2 changes: 2 additions & 0 deletions docs/data/migration/migration-data-grid-v8/migration-data-grid-v8.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ productId: x-data-grid

# Migration from v8 to v9

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

<p class="description">This guide describes the changes needed to migrate the Data Grid from v8 to v9.</p>

## Introduction
Expand Down
2 changes: 2 additions & 0 deletions docs/data/migration/migration-pickers-v8/migration-pickers-v8.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ productId: x-date-pickers

# Migration from v8 to v9

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

<p class="description">This guide describes the changes needed to migrate the Date and Time Pickers from v8 to v9.</p>

## Introduction
Expand Down
2 changes: 2 additions & 0 deletions docs/data/migration/migration-tree-view-v8/migration-tree-view-v8.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ productId: x-tree-view

# Migration from v8 to v9

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

<p class="description">This guide describes the changes needed to migrate the Tree View from v8 to v9.</p>

## Introduction
Expand Down
2 changes: 2 additions & 0 deletions docs/public/_redirects
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@
# should all be prefixed with x-

/r/x-get-license https://mui.com/pricing/ 302
/r/x-license-account https://mui.com/store/account/licenses/ 302
/r/x-license-key-upgrade https://support.mui.com/hc/en-us/articles/26762005295516-How-can-I-generate-a-v9-license-key/ 302
/r/x-license-eula https://mui.com/legal/mui-x-eula/ 302
/r/x-license-annual https://mui.com/legal/mui-x-eula/#annual-license 302
/r/x-license-trial https://mui.com/x/introduction/licensing/#evaluation-trial-licenses 302
Expand Down
31 changes: 31 additions & 0 deletions docs/src/modules/components/V9LicenseUpgradeWarning.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
import { MarkdownElement } from '@mui/internal-core-docs/MarkdownDocs';

export default function V9LicenseUpgradeWarning() {
return (
<MarkdownElement>
<aside className="MuiCallout-root MuiCallout-warning">
<div className="MuiCallout-icon-container">
<svg focusable="false" aria-hidden="true" viewBox="0 0 20 20">
<use xlinkHref="#warning-icon" />
</svg>
</div>
<div className="MuiCallout-content">
<p>
If you&apos;re upgrading from v8 to v9, you&apos;ll need to generate a new license key
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/">
Copy link
Copy Markdown
Member

@LukasTy LukasTy Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/">

Copy link
Copy Markdown
Member

@oliviertassinari oliviertassinari Apr 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member Author

@aemartos aemartos Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reverted.

How can I generate a v9 license key?
</a>{' '}
for step-by-step instructions.
</p>
<p>
When it&apos;s time to renew, you&apos;ll need to choose which key to renew, note that
v9 renewals are priced differently from v8 renewals.
</p>
</div>
</aside>
</MarkdownElement>
);
}
5 changes: 5 additions & 0 deletions packages/x-license/src/Watermark/Watermark.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,11 @@ function Watermark(props: WatermarkProps) {
}}
>
{getLicenseErrorMessage(licenseStatus.status)}
{process.env.NODE_ENV !== 'production' && (
<div style={{ fontSize: 12, letterSpacing: 1, marginTop: 8 }}>
Open the browser console for details on how to resolve this.
</div>
)}
</div>
);
}
Expand Down
8 changes: 5 additions & 3 deletions packages/x-license/src/utils/licenseErrorMessageUtils.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,10 +63,12 @@ export function showLicenseKeyVersionMismatchError() {
showError([
'MUI X: License key version mismatch.',
'',
'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).',
Copy link
Copy Markdown
Member

@mnajdova mnajdova Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).',

Copy link
Copy Markdown
Member

@mnajdova mnajdova Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member

@oliviertassinari oliviertassinari Apr 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member Author

@aemartos aemartos Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

'Each major version uses a different license key format, so the key needs to be regenerated — your existing license is not lost.',
'',
'To resolve this, you can either get an new license key at https://mui.com/r/x-get-license or from your account profile at https://mui.com/store/account/licenses/, or downgrade to an older MUI X version that matches your current license key.',
'To resolve this, you can either:',
'- Generate a new key compatible with the installed version from your account at https://mui.com/r/x-license-account/ (free for existing customers, the new key inherits your current expiration date). More details at https://mui.com/r/x-license-key-upgrade/.',
'- Or downgrade the MUI X packages to the major version that matches your current license key.',
]);
}

Expand Down
Loading
⚡