Skip to content

docs: clarify mid vs mid2 offline license key compatibility #5404

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

Merged
mshabarov merged 3 commits into from
Mar 31, 2026
+33 −2
Merged

docs: clarify mid vs mid2 offline license key compatibility #5404

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2c99069
docs: clarify mid vs mid2 offline license key compatibility
mcollovati Mar 26, 2026
fc39c15
Apply suggestions from code review
mcollovati Mar 31, 2026
b9f49ac
Merge branch 'main' into chore/improve-license-mid-mid2-docs
mcollovati Mar 31, 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
27 changes: 27 additions & 0 deletions articles/flow/configuration/licenses/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,23 @@

Each offline license key is tied to the machine ID, in the form of `mid-xxxxxxxx-xxxxxxxx` (License Checker version 2 or earlier) or `mid2-xxxxxxxx-xxxxxxxx` (`V2` key, since License Checker version 3). You'll have to submit that to `https://vaadin.com/myaccount/licenses`, so as to download an offline license key.

The machine ID format you need depends on your Vaadin version:

[cols="1,1,1"]
|===
|Machine ID Format |Key File |Vaadin Version

|`mid-xxxxxxxx-xxxxxxxx`
|[filename]`offlineKey`
|24.9 and earlier

|`mid2-xxxxxxxx-xxxxxxxx`
|[filename]`offlineKeyV2`
|24.10 and later
|===

Using the wrong key type causes an "Invalid offline key" error. If you work with both old and new Vaadin versions, download both key types.

Once you've downloaded the [filename]`offlineKey` or [filename]`offlineKeyV2` file -- remove any [filename]`.txt` suffix-- you should place it in your home directory:

[.example]
Expand Down Expand Up @@ -135,6 +152,16 @@
mvn com.vaadin:vaadin-maven-plugin:download-offline-license
----

[IMPORTANT]
====
The `download-offline-license` goal is only available in the Vaadin 24.10+ Maven plugin and always generates a `mid2` machine ID. This key does not work with Vaadin 24.9 or earlier.

Check warning on line 157 in articles/flow/configuration/licenses/index.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.Versions] Don't refer to a specific Vaadin version.

Raw Output:
{"message": "[Vaadin.Versions] Don't refer to a specific Vaadin version.", "location": {"path": "articles/flow/configuration/licenses/index.adoc", "range": {"start": {"line": 157, "column": 159}}}, "severity": "WARNING"}

Check warning on line 157 in articles/flow/configuration/licenses/index.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.Versions] Don't refer to a specific Vaadin version.

Raw Output:
{"message": "[Vaadin.Versions] Don't refer to a specific Vaadin version.", "location": {"path": "articles/flow/configuration/licenses/index.adoc", "range": {"start": {"line": 157, "column": 62}}}, "severity": "WARNING"}

For **Vaadin 24.9 or earlier** projects, you must obtain the `mid` machine ID manually:

Check warning on line 159 in articles/flow/configuration/licenses/index.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.Versions] Don't refer to a specific Vaadin version.

Raw Output:
{"message": "[Vaadin.Versions] Don't refer to a specific Vaadin version.", "location": {"path": "articles/flow/configuration/licenses/index.adoc", "range": {"start": {"line": 159, "column": 7}}}, "severity": "WARNING"}

. Attempt to build or run your project with a commercial component while offline. The `mid` machine ID is printed in the build error output.
. Use that `mid` machine ID to download the correct offline key from https://vaadin.com/myaccount/licenses.

Check failure on line 162 in articles/flow/configuration/licenses/index.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use '(?-i)Vaadin' instead of 'vaadin'.

Raw Output:
{"message": "[Vale.Terms] Use '(?-i)Vaadin' instead of 'vaadin'.", "location": {"path": "articles/flow/configuration/licenses/index.adoc", "range": {"start": {"line": 162, "column": 78}}}, "severity": "ERROR"}
====


[[server-license-key]]
== Validation on CI/CD or Build Server
Expand Down
8 changes: 6 additions & 2 deletions articles/flow/kb/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,8 +140,12 @@
.+++<h3>Invalid Offline Key</h3>+++
[%collapsible]
====
Either `offlineKey` is invalid or you are running License Checker 2 with a version 2 offline key (`mid2-xxxxxxxx-xxxxxxxx`).
Go to https://vaadin.com/myaccount/licenses#offline-license-key and download and install a proper version 1 key.
This error can occur in the following situations:

- **Version mismatch**: The offline key type does not match your Vaadin version. Vaadin 24.10 and later require a `mid2` (v2) key, while Vaadin 24.9 and earlier require a `mid` (v1) key. For Vaadin 24.10 or later, run `mvn com.vaadin:vaadin-maven-plugin:download-offline-license` to obtain the `mid2` machine ID. For Vaadin 24.9 or earlier, obtain the `mid` machine ID from the build error output and download the correct key from https://vaadin.com/myaccount/licenses.

Check warning on line 145 in articles/flow/kb/index.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.Versions] Don't refer to a specific Vaadin version.

Raw Output:
{"message": "[Vaadin.Versions] Don't refer to a specific Vaadin version.", "location": {"path": "articles/flow/kb/index.adoc", "range": {"start": {"line": 145, "column": 318}}}, "severity": "WARNING"}

Check warning on line 145 in articles/flow/kb/index.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.Versions] Don't refer to a specific Vaadin version.

Raw Output:
{"message": "[Vaadin.Versions] Don't refer to a specific Vaadin version.", "location": {"path": "articles/flow/kb/index.adoc", "range": {"start": {"line": 145, "column": 192}}}, "severity": "WARNING"}

Check warning on line 145 in articles/flow/kb/index.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.Versions] Don't refer to a specific Vaadin version.

Raw Output:
{"message": "[Vaadin.Versions] Don't refer to a specific Vaadin version.", "location": {"path": "articles/flow/kb/index.adoc", "range": {"start": {"line": 145, "column": 138}}}, "severity": "WARNING"}

Check warning on line 145 in articles/flow/kb/index.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.Versions] Don't refer to a specific Vaadin version.

Raw Output:
{"message": "[Vaadin.Versions] Don't refer to a specific Vaadin version.", "location": {"path": "articles/flow/kb/index.adoc", "range": {"start": {"line": 145, "column": 82}}}, "severity": "WARNING"}
- **Wrong key file**: The [filename]`offlineKey` or [filename]`offlineKeyV2` file contains an invalid or corrupted key.

See <<{articles}/flow/configuration/licenses#offline-license-key,Offline License Key>> for details on which key type to use for your Vaadin version.
====

// end::licenses[]
Loading