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

* docs: clarify mid vs mid2 offline license key compatibility

The download-offline-license Maven goal always generates a mid2 machine
ID, but Vaadin 24.9 and earlier only accept mid keys. This causes
confusing "Invalid offline key" errors.

Add a version compatibility table to the offline license section, a
warning that the Maven goal only works for Vaadin 25+, and improve the
related troubleshooting entry in the knowledge base.

* Apply suggestions from code review

Co-authored-by: Mikhail Shabarov <61410877+mshabarov@users.noreply.github.com>

---------

Co-authored-by: Mikhail Shabarov <61410877+mshabarov@users.noreply.github.com>

Author: mcollovati

articles/flow/configuration/licenses/index.adoc

@@ -62,9 +62,9 @@ The banner links to the https://vaadin.com/commercial-license-info[Commercial Li
 <source-info group="Maven"></source-info>
 mvn package -Pproduction -Dvaadin.commercialWithBanner
 ----
-[source,groovy]
+[source,terminal]
 ----
-<source-info group="Groovy"></source-info>
+<source-info group="Gradle"></source-info>
 ./gradlew build -Pvaadin.productionBuild -Pvaadin.commercialWithBanner
 ----
 --
@@ -106,6 +106,23 @@ If your local development environment is offline and can't reach `vaadin.com`, y
 
 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.
 
+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]
@@ -162,6 +179,16 @@ mvn dependency:get -Dartifact=com.vaadin:license-checker-machineid:1.8.1 && java
 ----
 --
 
+[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.
+
+For **Vaadin 24.9 or earlier** projects, you must obtain the `mid` machine ID manually:
+
+. 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.
+====
+
 
 [[server-license-key]]
 == Validation on CI/CD or Build Server

articles/flow/kb/index.adoc

@@ -120,4 +120,32 @@ This is a known error in `SSLHandshakeException` reported by users of WebSphere
 See the following discussion for more details: https://vaadin.com/forum/t/running-mpr-project-on-websphere-liberty-fails-with-suncertpathbuilderexcep/160675.
 ====
 
+[[offline-license-legacy-key]]
+.+++<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.
+====
+
+[[offline-license-invalid-format]]
+.+++<h3>Invalid Machine ID Format</h3>+++
+[%collapsible]
+====
+Either `offlineKey` contains a version 2 offline key (`mid2-xxxxxxxx-xxxxxxxx`) or `offlineKeyV2` contains a version 1 key (`mid-xxxxxxxx-xxxxxxxx`).
+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.
+====
+
+[[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.
+- **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[]