JavaFX "runtime components are missing" in CI - Fix the JavaFX Modules

Since JDK 11, JavaFX is a separate set of modules, not part of the JDK. Launching a JavaFX app without those modules on the module path fails with "runtime components are missing".

What this error means

A JavaFX app or UI test aborts at launch with Error: JavaFX runtime components are missing, and are required to run this application. The same code ran on an old JDK 8 that bundled JavaFX.

java

Error: JavaFX runtime components are missing, and are required to run this application

Common causes

JavaFX modules not on the module path

The OpenJFX modules (javafx.controls, javafx.fxml, ...) must be provided explicitly on JDK 11+. Without --module-path/--add-modules the launcher cannot find them.

A main class that extends Application launched directly

Launching the Application subclass without the modules trips an early check. A non-Application launcher main is one workaround, but the modules are still required.

How to fix it

Provide the OpenJFX modules at launch

Point the launcher at the JavaFX SDK and request the needed modules.

.github/workflows/ci.yml

- run: >
    java
    --module-path ${JAVAFX_HOME}/lib
    --add-modules javafx.controls,javafx.fxml
    -jar app.jar

Or depend on OpenJFX via the build tool

Use the javafx plugin / dependencies so the modules are resolved and run is configured.

build.gradle

plugins { id 'org.openjfx.javafxplugin' version '0.1.0' }
javafx {
  version = '21'
  modules = ['javafx.controls', 'javafx.fxml']
}

How to prevent it

Treat JavaFX as an explicit dependency on JDK 11+, supply its modules via the build plugin, and run UI tests under a virtual display (Xvfb) on headless CI.