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.

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:
<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:
mvn -B clean package -Pproduction[INFO] --- vaadin:24.5.0:build-frontend (frontend) @ shop ---
[INFO] Running the frontend build
[INFO] Production bundle is builtThe 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:
unzip -l target/shop.jar | grep -E 'META-INF/VAADIN/(webapp|config)' | head 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.jsIf 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.
unzip -p target/shop.jar BOOT-INF/classes/META-INF/VAADIN/config/flow-build-info.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:
vaadin.productionMode=trueA 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:
vaadin.productionMode=truejava -jar target/shop.jar --spring.profiles.active=prodThe application's startup log says which mode it chose:
INFO c.v.f.s.VaadinServletContext : Starting in production modeIf 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:
[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:
npm ERR! code ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/@vaadin%2fvaadin-core failedRun the build in the same environment as the pipeline and read the output. Confirm Node:
node --version
npm config get registryThe 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:
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.
mvn -B vaadin:clean-frontend
rm -rf node_modules target
mvn -B clean package -Pproductionclean-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.


