Documentation

Documentation

Troubleshooting Production Mode

Advice when having problems taking Vaadin applications to production.

This page provides some suggestions in case you have problems taking Vaadin applications to production.

Verifying Production Mode Artifact

Vaadin Servlet configures itself from the flow-build-info.json file, which is located in the META-INF/VAADIN/config/ resource package.

The location of resources differs, though, for different artifact types. For example, the Spring Boot JAR file places resources into the BOOT-INF/classes/ folder in the JAR file. Whereas, the WAR archive puts them in the WEB-INF/classes/ folder.

If production mode has been activated, the contents of the flow-build-info.json should be as follows:

{
  "compatibilityMode": false,
  "productionMode": true,      (1)
  "enableDevServer": false,
  "chunks": {
    "fallback": {
      "jsModules": [
        "@vaadin/vaadin-grid/src/vaadin-grid-tree-toggle.js",
// etc etc
        "frontend://ironListConnector.js"
      ],
      "cssImports": [
      ]
    }
  }
}

  1. The productionMode property is set to true.

It’s very important that this file be precise once on the classpath in production mode. If the file is missing, Vaadin Servlet uses other means to examine whether it’s running in production mode: the value of the vaadin.productionMode system property; or the flow-server-production-mode.jar being present on the classpath, or similar.

Depending on the outcome, Vaadin may throw an exception at runtime like this:

Failed to determine project directory for dev mode...

Or it may return a message like this:

The compatibility mode is explicitly set to 'false', but there are neither 'flow-build-info.json' nor 'vite.config.ts' files

Vaadin may also decide to start in development mode. The Vaadin configuration is then governed by a different set of rules: for example, the project.basedir property or similar.

flow-build-info.json File

The project flow-build-info.json file is generated by the Vaadin plugin, in the prepare-frontend Maven goal. It’s then modified in the build-frontend task to enable production mode.

If the file is present multiple times on the classpath, then Vaadin tries to choose the right one coming from the main project. If it isn’t possible to do this, Vaadin prints a warning message and chooses the first flow-build-info.json file. This depends on the ordering in the classpath, which in turn may depend on the ordering of files in the file system or in the WAR/JAR archive.

This confusion can happen when a Vaadin add-on incorrectly includes the flow-build-info.json file in the JAR file. This is a bug in the add-on packaging, which needs to be fixed. Also, the flow-build-info.json file needs to be removed from the add-on’s JAR file.

For the reasons stated, make sure the flow-build-info.json file is on the classpath only once, and is always coming from your main project.

stats.json File

A file named META-INF/VAADIN/config/stats.json is generated by the Maven plugin, as well. It’s important to check for the presence of this file in the resources folder.

When packaging for production, a Vite executable is run. This happens in the build-frontend Maven goal. Vite is then responsible for packaging everything from frontend/ and node_modules into the pre-compiled JavaScript files bundle. The bundle is located in the META-INF/VAADIN/build/ resource folder. The folder contents should look like this:

├── FlowBootstrap.0b77bed3.js
├── FlowBootstrap.0b77bed3.js.br
├── FlowClient.947c8d40.js
├── FlowClient.947c8d40.js.br
├── generated-flow-imports-fallback.348e3eaf.js
├── generated-flow-imports-fallback.348e3eaf.js.br
├── generated-flow-imports.b6dfc59f.js
├── generated-flow-imports.b6dfc59f.js.br
├── indexhtml.e5efd5b3.js
├── indexhtml.e5efd5b3.js.br
├── webcomponenthtml-5467a14d.js
└── webcomponenthtml-5467a14d.js.br

Note, the hashes differ with each build.

Common Issues

Below are some common issues faced when attempting to go to production with an application, along with suggestions for resolving them.

The application won’t start after adding the flow-server-production-mode dependency.

One potential cause of this problem is that the build-frontend of the flow-maven-plugin wasn’t executed, either because the plugin is missing from the pom.xml file, or it’s missing in the configuration. To resolve this, add the flow-maven-plugin to your Maven build block. Make sure it’s visible in your production mode profile. Then enable the build-frontend goal.

When running multiple Vaadin applications on different ports on the same host, the browser tabs keeps reloading the page.

The cause of page reloading is possibly due to server session expiration caused by all Vaadin application having the same HTTP session cookie name (e.g., JSESSIONID). Cookies for a given host are shared across all of the ports on that host, even though "same-origin policy", typically used by web browsers, isolates content retrieved via different ports.

This mean the value from one application is overridden by another. To resolve this, configure a different HTTP session cookie name for each application instance. In a Spring Boot application, the cookie name can be set with the server.servlet.session.cookie.name property. Another possibility is to get the SessionCookieConfig instance from the ServletContext and use the setName(String) method to change cookie name.

See HTTP State Management Mechanism RFC for more information.

9A4AD367-94A0-4933-AE09-1A08016E6E58