Docs

Docs

Troubleshooting Production Mode

Guidance for when having problems taking Hilla applications to production.

This article offers guidance in the event that you have problems taking Hilla applications to production.

Verify 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 for different artifact types:

  • Spring Boot JAR file places resources into the BOOT-INF/classes/ folder in the JAR file; and

  • WAR archive places resources into the WEB-INF/classes/ folder.

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

Source code
flow-build-info.json
{
  "productionMode": true,
  "frontendHotdeploy": false
}

Notice that the productionMode property is set to true.

It’s very important to have this file on the class path in production mode only once. If the file is missing, Vaadin Servlet uses other means to examine whether it’s running in production mode, such as the value of the vaadin.productionMode system property.

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

Source code
Failed to determine project directory for dev mode...

Or it might read like this:

Source code
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. If so, the Vaadin configuration is then governed by a different set of rules (e.g., the project.basedir property or similar).

The project flow-build-info.json file is generated by the Vaadin plugin in the build-frontend Maven goal.

If the file is present multiple times on the class path, Vaadin tries to choose the right one, which should come from the main project. Sometimes it’s not possible to do so. In that case, Vaadin prints a warning message and chooses the first flow-build-info.json file, which depends on the class path ordering, which in turn may depend on the ordering of files on the file system or in the WAR/JAR archive.

This 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 that needs to be fixed. The flow-build-info.json file should be removed from the add-on’s JAR file.

For the reasons stated above, be sure to have the flow-build-info.json file on the class path only once, and always coming from your main project.

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:

Source code
├── 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

A common problem that may occur is that the application won’t start after building for production.

One potential cause of this is that the build-frontend goal of the vaadin-maven-plugin wasn’t executed, either because the plugin is missing from the pom.xml or it’s missing configuration.

To fix this, add the vaadin-maven-plugin to your Maven build block and enable the build-frontend goal.