Docs

Docs

Knowledge Base

TODO this is the beginning of a potential 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.

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:

Source code
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:

Source code
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:

Source code
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. Otherwise you might receive the following type of error during start up:

Source code
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 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) to run Design System Publisher.

Licenses

You can contact license@vaadin.com for further help.

I Get A Trial Message Although I Have A Valid License

Verify that you have a valid license by going to https://vaadin.com/pro/validate-license. 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: https://vaadin.com/forum/t/running-mpr-project-on-websphere-liberty-fails-with-suncertpathbuilderexcep/160675.

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 https://vaadin.com/myaccount/licenses#offline-license-key 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 https://vaadin.com/myaccount/licenses#offline-license-key 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 https://vaadin.com/myaccount/licenses.

  • Wrong key file: The offlineKey or offlineKeyV2 file contains an invalid or corrupted key.

See Offline License Key for details on which key type to use for your Vaadin version.

Updated –