> Markdown version of [Knowledge Base](https://vaadin.com/docs/next/flow/kb). Section index: [llms.txt](https://vaadin.com/docs/next/flow/llms.txt)
# Knowledge Base
## Design System Publisher
You may have some issues with Design System Publisher. Here are some common ones and suggestions on how to troubleshoot them.
Bug reports and feature requests can be submitted at the [Design System Publisher GitHub repository](https://github.com/vaadin/design-system-publisher/issues).
### Browser Doesn't Match Filesystem Content
To speed up the start process, the Design System Publisher caches some resources, internally. Sometimes, caches tend to get out of sync and need cleaning. Run the following command to flush the internal caches and restart the development server to see if it fixes the issue:
```terminal
npm run dspublisher:clean
```
The issue may also concern the browser’s cache. In case the above doesn’t help, try cleaning the browser’s cache, as well.
### Page Heading Changes Not Rendered
There’s one caveat about the page headings. On a regular page, if you change the main heading in the AsciiDoc (i.e., `= Page Heading`), you’ll see the heading update as expected. But if you use `layout: tabbed-page` in the page front matter, the tabbed page heading is actually retrieved from the front matter’s title field. Therefore, you may want to change that instead.
### Application Won't Start on Linux
When the application won’t start on Linux, make sure that the necessary dependencies are installed by running the following at the command-line:
```terminal
sudo apt install build-essential autoconf automake libtool pkg-config libpng-dev nasm zlib1g-dev
```
### Development Server Fails to Start
The `npm run dspublisher:start` script, which starts up the development server, has certain expectations about your development environment. The development server may fail to start for one of the following reasons:
#### npm Ignoring Scripts
If you configure `npm` with `ignore-scripts=true`, the startup fails. An example error message for this is the following:
```
Error in "/Users/[username]/.npm/_npx/c089b35bd0e8ac07/node_modules/@vaadin/dspublish
er/node_modules/gatsby-transformer-sharp/gatsby-node.js":
Something went wrong installing the "sharp" module
Cannot find module '../build/Release/sharp-darwin-arm64v8.node'
```
Remove the `ignore-scripts` configuration and delete the `/.npm/_npx` from the home directory to fix the issue.
#### Missing Xcode Command Line Tools
On macOS, you need [install the `Xcode` Command Line Tools](https://www.freecodecamp.org/news/install-xcode-command-line-tools/). Otherwise you might receive the following type of error during start up:
```
dsp@[version]:start ████████████████████ Initializing
npx,concurrently,--kill-others,--raw,"npx @vaadin/dspublisher@[version] --develop","mvn -C" failed with code 1
```
#### Gatsby on Windows
Design System Publisher is based on Gatsby, which has known issues on Windows. If you’re using Windows, see [Gatsby on Windows](https://www.gatsbyjs.com/docs/how-to/local-development/gatsby-on-windows/) for more information.
It’s recommended to use Linux or macOS as your development platform. On Windows, you can use [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) to run Design System Publisher.
## Licenses
You can contact for further help.
### I Get A Trial Message Although I Have A Valid License
Verify that you have a valid license by going to . If not, either your company’s license administrator hasn’t yet assigned a seat for you, or the license is no longer valid.
### SSLHandshakeException with Multiplatform Runtime
This is a known error in `SSLHandshakeException` reported by users of WebSphere Liberty and WildFly in Docker. See the following discussion for more details: .
### Detected an Offline License Version 1, but Version 2 is required
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:
- **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 and download and install a version 2 key.
### Invalid Machine ID Format
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 and download and install the correct key type.
### Invalid Offline Key
This error can occur in the following situations:
- **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 .
- **Wrong key file**: The `offlineKey` or `offlineKeyV2` file contains an invalid or corrupted key.
See [Offline License Key](https://vaadin.com/docs/next/flow/configuration/licenses.md#offline-license-key) for details on which key type to use for your Vaadin version.