Skip to content

docs: update offline license key docs for License Checker 2.3.1 backport (v24) #5819

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
mcollovati wants to merge 3 commits into
base: v24
Choose a base branch
from
Open

docs: update offline license key docs for License Checker 2.3.1 backport (v24) #5819

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
be7a811
docs: update offline key docs for License Checker 2.3.1 backport
mcollovati Jul 16, 2026
d20452e
docs: expand offline key troubleshooting for JNA failures and backport
mcollovati Jul 17, 2026
c27a314
docs: fix Vale lint issues in license docs
mcollovati Jul 17, 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
2 changes: 2 additions & 0 deletions .github/styles/Vaadin/Abbr.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ exceptions:
- JAR
- JDBC
- JDK
- JNA
- JNL
- JOOQ
- JPA
Expand All @@ -77,6 +78,7 @@ exceptions:
- NAT
- NGINX
- OCR
- OSHI
- OSV
- OWASP
- PATH
Expand Down
1 change: 1 addition & 0 deletions .github/styles/config/vocabularies/Docs/accept.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ async
automount
autorun
Azure
[bB]ackport(ed|ing|s)?
[bB]oldens
[bB]oolean
[bB]orderless
Expand Down
26 changes: 16 additions & 10 deletions articles/flow/configuration/licenses/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,25 +102,29 @@
[[offline-license-key]]
=== Offline License Key

pass:[<!-- vale Vaadin.Versions = NO -->]

If your local development environment is offline and can't reach `vaadin.com`, you'll need to get an offline license key.

Each offline license key is tied to the machine ID, in the form of `mid-xxxxxxxx-xxxxxxxx` (deprecated) or [since:com.vaadin:vaadin@V24.10]##`mid2-xxxxxxxx-xxxxxxxx` (`V2` key)##. You'll have to submit that to `https://vaadin.com/myaccount/licenses`, so as to download an offline license key.
Each offline license key is tied to the machine ID, in the form of `mid-xxxxxxxx-xxxxxxxx` (deprecated) or [since:com.vaadin:vaadin@V24.9]##`mid2-xxxxxxxx-xxxxxxxx` (`V2` key)##. 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
|24.9 and later

|`mid-xxxxxxxx-xxxxxxxx`
|[filename]`offlineKey`
|24.8 and earlier
|===

Support for the `mid2`/`offlineKeyV2` format was backported to Vaadin 24.9, so it's available in 24.9 and all later versions. Versions that support the `V2` key still also accept the legacy `mid`/`offlineKey` format.

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:
Expand Down Expand Up @@ -181,14 +185,16 @@

[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.
The `download-offline-license` goal is only available in the Vaadin 24.10+ Maven plugin, where it always generates a `mid2` machine ID.

For **Vaadin 24.9 or earlier** projects, you must obtain the `mid` machine ID manually:
Vaadin 24.9 also accepts the `mid2`/`offlineKeyV2` key, but it doesn't include the goal. On Vaadin 24.9 and earlier, obtain the machine ID manually:

. Run the above command to get the `mid`.
. Use that `mid` machine ID to download the correct offline key from https://vaadin.com/myaccount/licenses.
. Attempt to build or run your project with a commercial component while offline. The machine ID and the offline key download URL are printed in the log output -- a `mid2` on Vaadin 24.9, or a `mid` on 24.8 and earlier. To print the legacy `mid`, you can also run the `license-checker-machineid` command shown above.
. Use that machine ID to download the matching offline key from https://vaadin.com/myaccount/licenses.

Check failure on line 193 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": 193, "column": 73}}}, "severity": "ERROR"}
====

pass:[<!-- vale Vaadin.Versions = YES -->]


[[server-license-key]]
== Validation on CI/CD or Build Server
Expand Down
12 changes: 9 additions & 3 deletions articles/flow/kb/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,8 +124,10 @@
.+++<h3>Detected an Offline License Version 1, but Version 2 is required</h3>+++
[%collapsible]
====
License Checker 3 requires version 2 offline key (`mid2-xxxxxxxx-xxxxxxxx`), but it detected locally only a version 1 key (`mid-xxxxxxxx-xxxxxxxx`).
Go to https://vaadin.com/myaccount/licenses#offline-license-key and download and install a version 2 key.
This message appears when a version 1 offline key (`mid-xxxxxxxx-xxxxxxxx`) is installed, but the License Checker can't compute this machine's version 1 machine ID. There are two common causes:

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

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.ThereIs] Don't start a sentence with 'There are'.

Raw Output:
{"message": "[Vaadin.ThereIs] Don't start a sentence with 'There are'.", "location": {"path": "articles/flow/kb/index.adoc", "range": {"start": {"line": 127, "column": 166}}}, "severity": "WARNING"}

- *The version 1 machine ID can't be computed.* The `mid` machine ID is derived from hardware details through the OSHI library and its native JNA component. If the JNA native library (for example, `jna.dll` on Windows) is blocked -- commonly by antivirus or endpoint-security software -- or otherwise fails to load, the version 1 machine ID can't be generated, and this message is shown instead of the real error. Re-run the build with debug logging (`mvn -X` or `./gradlew --debug`) and look for a `Failed to generate v1 Machine ID` entry to confirm, then resolve the underlying JNA or native-library problem (for example, allow-list the file, or use a JNA version compatible with your environment).
- *You want to migrate to a version 2 key.* Version 2 keys (`mid2-xxxxxxxx-xxxxxxxx`) don't rely on OSHI or JNA. Go to https://vaadin.com/myaccount/licenses#offline-license-key and download and install a version 2 key.
====

[[offline-license-invalid-format]]
Expand All @@ -136,16 +138,20 @@
Verify that you have a valid license by going to https://vaadin.com/myaccount/licenses#offline-license-key and download and install the correct key type.
====

pass:[<!-- vale Vaadin.Versions = NO -->]

[[offline-license-invalid-key]]
.+++<h3>Invalid Offline Key</h3>+++
[%collapsible]
====
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.
- **Version mismatch**: The offline key type does not match your Vaadin version. The `mid2`/`offlineKeyV2` format is supported in Vaadin 14.14, 23.6, and 24.9 and later; earlier versions accept only the legacy `mid`/`offlineKey` format. In Vaadin 24.10 and later, run `mvn com.vaadin:vaadin-maven-plugin:download-offline-license` to obtain the `mid2` machine ID. In earlier versions -- which don't include that goal -- obtain the machine ID from the build or run logs and download the correct key from https://vaadin.com/myaccount/licenses.
- **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.
====

pass:[<!-- vale Vaadin.Versions = YES -->]

// end::licenses[]
Loading