Troubleshooting Production Mode
Verifying the 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, for example:
-
Spring Boot
JAR
file places resources into theBOOT-INF/classes/
folder in theJAR
file; -
WAR
archive places resources into theWEB-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": [
]
}
}
}
-
The
productionMode
property is set totrue
.
It’s very important to have this file exactly 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:
Failed to determine project directory for dev mode...
or
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).
The project flow-build-info.json
file is generated by the Vaadin plugin, in the prepare-frontend
Maven goal, 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, which 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 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 and the flow-build-info.json
file removed from the add-on’s JAR
file.
For the reasons stated above, keep in mind that you need to have the flow-build-info.json
file on the classpath 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 (the hashes differ with every build):
├── vaadin-2-18d67c4ccff7e93b081a.cache.js
├── vaadin-2-18d67c4ccff7e93b081a.cache.js.gz
├── vaadin-3-b0147df339bf18eb7618.cache.js
├── vaadin-3-b0147df339bf18eb7618.cache.js.gz
├── vaadin-4-ee1d2e45569f7eca4292.cache.js
├── vaadin-4-ee1d2e45569f7eca4292.cache.js.gz
├── vaadin-5-5e9292474e82143d0a27.cache.js
├── vaadin-5-5e9292474e82143d0a27.cache.js.gz
├── vaadin-bundle-19a00eae62ad7cddd291.cache.js
├── vaadin-bundle-19a00eae62ad7cddd291.cache.js.gz
├── vaadin-bundle.es5-b1c1a3cc054c62ad7949.cache.js
├── vaadin-bundle.es5-b1c1a3cc054c62ad7949.cache.js.gz
└── webcomponentsjs
├── bundles
│ ├── webcomponents-ce.js
│ ├── webcomponents-ce.js.map
│ ├── webcomponents-sd-ce.js
│ ├── webcomponents-sd-ce.js.map
│ ├── webcomponents-sd-ce-pf.js
│ ├── webcomponents-sd-ce-pf.js.map
│ ├── webcomponents-sd.js
│ └── webcomponents-sd.js.map
├── custom-elements-es5-adapter.js
├── LICENSE.md
├── package.json
├── README.md
├── src
│ └── entrypoints
│ ├── custom-elements-es5-adapter-index.js
│ ├── webcomponents-bundle-index.js
│ ├── webcomponents-ce-index.js
│ ├── webcomponents-sd-ce-index.js
│ ├── webcomponents-sd-ce-pf-index.js
│ └── webcomponents-sd-index.js
├── webcomponents-bundle.js
├── webcomponents-bundle.js.map
└── webcomponents-loader.js
Common Issues
- After adding the
flow-server-production-mode
dependency, the application no longer starts -
One potential cause of this problem is that the
build-frontend
of theflow-maven-plugin
wasn’t executed, either because the plugin is missing from thepom.xml
or it’s missing in the configuration. To fix this, add theflow-maven-plugin
to your Mavenbuild
block (make sure it’s visible in your production mode profile), and enable thebuild-frontend
goal.
9A4AD367-94A0-4933-AE09-1A08016E6E58