Skip to content
javahacks.dev
Vaadin

Fix Vaadin Production Build Blank Page and Frontend Errors

Fix a Vaadin app that shows a blank page after deployment by building with the production profile and checking the packaged frontend bundle.

7 min read
Summarize in AI
Flat illustration of a browser page built from server-side components, with the Vaadin, Docker and Spring logos.

The Vaadin application works with mvn spring-boot:run and shows a blank white page when you run the production jar. The browser console may report Failed to load resource for files under /VAADIN/, or Could not find the frontend bundle, or nothing at all, with the application server logging a cheerful Started. Vaadin Flow builds a JavaScript frontend bundle (using Node and Vite behind the scenes) from the components your application uses, and the development server builds it on the fly. A production jar needs that bundle built ahead of time and included in the artifact, and production mode switched on. The blank page means one of these links is missing. This post lists six causes in order of how often they occur, with the check that confirms each. Examples use Vaadin 24 and Spring Boot 4, built with Maven; the Gradle plugin follows the same logic.

Cause 1: the jar was built without the production profile

By default mvn package builds the application for development: it does not compile the production frontend bundle. The result runs fine from spring-boot:run, where the development server compiles on demand, and shows a blank page as a jar. Vaadin's Maven plugin has a build-frontend goal that runs in a production profile, which the Vaadin starter projects define:

pom.xmlXML
<profile>
  <id>production</id>
  <build>
    <plugins>
      <plugin>
        <groupId>com.vaadin</groupId>
        <artifactId>vaadin-maven-plugin</artifactId>
        <version>${vaadin.version}</version>
        <executions>
          <execution>
            <id>frontend</id>
            <phase>compile</phase>
            <goals>
              <goal>prepare-frontend</goal>
              <goal>build-frontend</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</profile>

Build with the profile explicitly:

Shell
mvn -B clean package -Pproduction
Text
[INFO] --- vaadin:24.5.0:build-frontend (frontend) @ shop ---
[INFO] Running the frontend build
[INFO] Production bundle is built

The build-frontend line is the one to look for. If your CI runs mvn package without -Pproduction, that is the cause, and the fix is a one-flag change in the pipeline. The configuration and the production mode requirements are described in the Vaadin production documentation.

Cause 2: confirm the bundle is in the jar

Do not trust the build log; look inside the artifact. The compiled frontend lives under META-INF/VAADIN/webapp in the jar:

Shell
unzip -l target/shop.jar | grep -E 'META-INF/VAADIN/(webapp|config)' | head
Text
      612  BOOT-INF/classes/META-INF/VAADIN/config/flow-build-info.json
    19228  BOOT-INF/classes/META-INF/VAADIN/webapp/index.html
  1042113  BOOT-INF/classes/META-INF/VAADIN/webapp/VAADIN/build/vaadin-bundle-5c1e.cache.js

If there are no webapp entries, the bundle was not built or was excluded. Read flow-build-info.json: it records how the build was made.

Shell
unzip -p target/shop.jar BOOT-INF/classes/META-INF/VAADIN/config/flow-build-info.json
JSON
{
  "productionMode": true,
  "frontendHotdeploy": false
}

"productionMode": true is what a production artifact should say. false means the build ran in development mode: the plugin did not run in the profile you used, or something overrode it. When the file is missing entirely, the jar contains no Vaadin build information and the runtime has nothing to serve.

Cause 3: production mode is not on

Even with a correct bundle, the runtime must be told to use it. In a Spring Boot application, production mode is a property:

src/main/resources/application.propertiesproperties
vaadin.productionMode=true

A development-mode runtime looks for a Node-based dev server and the source frontend files, which are not in the jar, and fails with a blank page. The two states must match: a production bundle with development mode on in the runtime, or the reverse, both give the blank page. Set it for the production profile only, so local development keeps hot reload:

src/main/resources/application-prod.propertiesproperties
vaadin.productionMode=true
Shell
java -jar target/shop.jar --spring.profiles.active=prod

The application's startup log says which mode it chose:

Text
INFO  c.v.f.s.VaadinServletContext : Starting in production mode

If the log says development mode or Vaadin is running in DEBUG MODE, the property did not take effect. Check that the profile is active, that no environment variable overrides it (VAADIN_PRODUCTIONMODE=false), and that the property file is on the classpath. The way configuration sources override each other is explained in Spring Boot configuration precedence, and the inner workings of the Vaadin server-side model are in how the Vaadin Flow server-side model works.

Cause 4: the build could not run Node

The frontend build runs Node.js. Vaadin can download and use a local copy, or use the one on the machine. A CI image without Node, with a Node version that is too old, or a network that blocks the npm registry makes the frontend build fail, and, depending on the setup, the error is easy to miss in a long log:

Text
[ERROR] Failed to execute goal com.vaadin:vaadin-maven-plugin:24.5.0:prepare-frontend: Node.js version 16.20.0 is not supported. Vaadin requires Node 18 or later.

Or an npm failure:

Text
npm ERR! code ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/@vaadin%2fvaadin-core failed

Run the build in the same environment as the pipeline and read the output. Confirm Node:

Shell
node --version
npm config get registry

The remedies: install a supported Node in the image, allow the plugin to install its own (the Vaadin plugin can download Node to a local directory, which needs outbound network access), or point npm at your internal registry mirror in an .npmrc file. A Docker build is a common place for this: the build stage needs Node and network access, the final runtime stage needs neither. A multi-stage Dockerfile that builds with the production profile in the first stage and copies only the jar is the reliable shape, as in writing a Java Dockerfile the right way. Cache the npm directory between builds to avoid downloading hundreds of megabytes each time.

Cause 5: a proxy breaks the live connection

The page loads and then goes blank or becomes unresponsive, or shows a "Connection lost" overlay. Vaadin's server-side model keeps a live connection from the browser to the server session, using long polling or WebSocket (Atmosphere push), and a reverse proxy or load balancer that does not forward the upgrade request, or that times out idle connections, breaks it. The browser console shows WebSocket connection to 'wss://...' failed or repeated failed XHR calls.

Check the proxy configuration. For nginx, the upgrade headers and a longer read timeout are required for push:

Nginx
location / {
    proxy_pass http://shop:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 3600s;
}

Also check that the application knows it is behind a proxy so it builds correct URLs: server.forward-headers-strategy=framework in Spring Boot. A path prefix needs the Vaadin and Spring context path set accordingly, because the bundle's resource URLs are relative to it. Sticky sessions are required when more than one instance serves the application, since the UI state lives in the server session; without stickiness a request lands on an instance that has no such session and the page breaks. The connection model is the reason: how the Vaadin Flow server-side model works explains why the session is the application.

Cause 6: a stale frontend directory

A frontend directory left over from an earlier version of Vaadin or from a development session can make the production build use the wrong inputs. The generated files (frontend/generated, package.json, package-lock.json, vite.config.ts, the node_modules directory) are partly produced by the build and partly committed, and a mismatch between them and the Vaadin version in pom.xml after an upgrade produces a bundle that does not load. The telltale is a build that worked before a Vaadin version bump.

Shell
mvn -B vaadin:clean-frontend
rm -rf node_modules target
mvn -B clean package -Pproduction

clean-frontend removes the generated frontend files so the next build regenerates them. Review git status afterwards: files under frontend/generated should not be committed (add them to .gitignore), while package.json changes legitimately track the dependencies you add. After a Vaadin upgrade, delete package-lock.json and node_modules and rebuild once. The practical guide to building a whole application on this stack is in Vaadin and Spring Boot, and the broader guide in building web UIs with Vaadin.

Where this does not apply

If the page is blank in the development server too, the problem is in your view code or a client-side exception; open the browser console. If a single route is blank while others load, check that the view class has a @Route annotation and is in a scanned package, because an unreachable route shows the error page, not a blank one. And if the jar works locally but not in the container, compare the architecture and the Java version of the base image before suspecting the bundle. The full configuration property list is in the Vaadin Flow configuration reference.

Also inDevOps
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.