Docs

You are viewing documentation for an older Vaadin version. View latest documentation

Docs

Troubleshooting Production Mode

Guidance if you have problems taking Vaadin applications to production.

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 the BOOT-INF/classes/ folder in the jar file;

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

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

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

  1. Note that the productionMode property is set to true

It’s very important to have this file on classpath in production mode exactly once.

If the file is missing, Vaadin Servlet will use 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 'webpack.config.js' 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 Vaadin plugin, in the prepare-frontend Maven goal, then modified in build-frontend task to enable production mode.

If the file is present multiple times on the classpath, then Vaadin tries to choose which one is the right one which should be coming from the main project. Sometimes it’s not possible to do so, and then Vaadin prints a warning message and chooses the first flow-build-info.json file, which depends on the classpath 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 addon incorrectly includes the flow-build-info.json file in the jar file. That’s a bug in the addon packaging which need to be fixed and the flow-build-info.json file removed from addon’s jar file.

For the reasons stated above, keep in mind 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 Maven Plugin as well – it’s important to check for the presence of this file in the resources folder.

When packaging for production a webpack executable is run; this happens in the build-frontend Maven goal. Webpack is then responsible for packaging everything from frontend/ and node_modules into the precompiled JavaScript files bundle. The bundle is located in the META-INF/VAADIN/build/ resource folder. The folder contents should look like this (the hash is going to differ on 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 the flow-maven-plugin was not executed, either because the plugin is missing from the pom.xml or it is missing configuration. To fix this, add the flow-maven-plugin to your maven build block (make sure it is visible in your production mode profile), and enable the build-frontend goal.

7D5ED92D-B49C-47B0-ADED-936E9D2240E2