Fix: JavaFX Runtime Components Are Missing

“Error: JavaFX runtime components are missing, and are required to run this application” means the java command started a class that extends JavaFX's Applicationwithout JavaFX's modules on the module path, usually because JavaFX's jar files were put on the classpath instead. You fix it by loading JavaFX as modules: run the program through the JavaFX plugin for Maven or Gradle, add two flags to the java command, or use a JDK that already contains JavaFX. Every fix below is for JavaFX 27 on Java 25.

Here is a complete JavaFX program, and the commands that compile and run it with the JavaFX SDK (fix 3 below) on macOS or Linux:

A window titled "Hello", 320 by 120 pixels, with the words
"Hello, JavaFX" in the middle. Close it and the program ends.

What the error means#

The java command makes one extra check before it starts a program. If the main class extends javafx.application.Application, directly or through a parent class, it looks for JavaFX's javafx.graphics module among the loaded modules. (Since Java 9, the JDK is split into named modules, and JavaFX ships its jar files as modules too: each one declares a name and the packages it shares.) If that module is not loaded, java stops with the message before your main method runs.

A jar on the classpath, the plain list of folders and jars where Java finds classes, is never loaded as a named module, so JavaFX on the classpath does not count. That is the usual cause: Maven, Gradle and IDE libraries put every dependency on the classpath unless told otherwise. When JavaFX is missing altogether, the message is a different one. Both cases, from a terminal:

In the first command, JavaFX's jars are on the classpath. Java can load HelloApp and see that its parent class is Application, but it finds no javafx.graphics module. In the second, JavaFX is nowhere, so Java cannot even load HelloApp. The cure is the same for both.

Key idea

JavaFX has to be loaded as modules: found through --module-path and named with --add-modules. On the classpath, it gives the runtime components error.

Why JavaFX is not included in the JDK#

JavaFX 8 shipped inside Oracle's JDK 8. In March 2018 Oracle announced that, starting with JDK 11, JavaFX would be a separate download, decoupled from the JDK, and named the module system added in Java 9 as what made the split practical. Since then JavaFX has been developed as OpenJFX, an OpenJDK project with its own release every six months. JavaFX 27, the current release, needs JDK 25 or later.

So Oracle JDK 25 and the usual OpenJDK builds, such as Eclipse Temurin, have no JavaFX: you bring it yourself. The SDK is a download linked from openjfx.io, and Maven and Gradle fetch JavaFX from Maven Central, where it is published under the group org.openjfx. The story of AWT, Swing and JavaFX is in the JavaFX overview.

Fix 1: Maven and the JavaFX Maven plugin#

In a Maven project, JavaFX is an ordinary dependency, and the JavaFX Maven plugin starts the program with the module flags. With HelloApp in the package com.example, the pom.xml needs:

javafx-controls brings javafx-graphics and javafx-base with it, and Maven downloads the files built for your operating system. Add javafx-fxml as well if you use FXML. mainClass names your class, and each option is passed to java; this one silences the warnings explained in fix 3. Then run:

The plugin starts java with --module-path and --add-modules for the JavaFX jars, and the window opens. A project with the Maven wrapper runs ./mvnw javafx:run instead. The details of the pom.xml are in Maven and Gradle.

Fix 2: Gradle and the JavaFX Gradle plugin#

Gradle has a plugin of its own, org.openjfx.javafxplugin. In build.gradle.kts:

The javafx block picks the JavaFX version and modules, and the plugin adds the matching jars for your operating system. When you run ./gradlew run (gradlew run on Windows), the plugin moves those jars from the classpath to the module path and adds --add-modules. In a Groovy build.gradle, the same block reads modules = [ 'javafx.controls' ], and the plugin line is id 'org.openjfx.javafxplugin' version '0.1.0'. As with Maven, start the program with the Gradle run task, not with the Run arrow next to main.

Fix 3: the JavaFX SDK with --module-path and --add-modules#

Without a build tool, download the JavaFX 27 SDK for your operating system and processor (aarch64 on an Apple Silicon Mac) and unzip it. Its libfolder holds JavaFX's modules as jar files. Both javac and java need to be told about it, as in the commands at the top of this page. These are the same on Linux, Ubuntu included. In the Windows Command Prompt:

• --module-path says where the modules are: the SDK's lib folder, not the SDK folder above it. Both commands need it.
• --add-modules javafx.controls says which modules to load. javafx.controls brings javafx.graphics and javafx.base; list more with commas, as in javafx.controls,javafx.fxml. Both commands need it.
• --enable-native-access=javafx.graphics is for java only. Since JDK 24 the JVM prints warnings when a module loads native code (code compiled for your system, which JavaFX uses to draw) without permission, and the JavaFX 24 release notes ask applications to grant it. Add javafx.media and javafx.web to the list if you use them.

%PATH_TO_FX% works in the Command Prompt only. In PowerShell, write the path out in full, in quotes, in both commands.

In IntelliJ IDEA, Eclipse, VS Code and NetBeans#

An IDE needs the same flags, entered once in the run configuration. They go in the VM options, the settings for the JVM itself. Program arguments are a different box: what you type there reaches your main method in args, and the error stays.

• IntelliJ IDEA: Run, Edit Configurations, then Modify options, Add VM options. Add the lib folder under File, Project Structure, Libraries too, so the editor can compile the imports.
• Eclipse: Run, Run Configurations, your Java Application, the Arguments tab, VM arguments.
• NetBeans: the project's Properties, Run, VM Options.
• VS Code: vmArgs in .vscode/launch.json, as below, then run with F5.

On Windows, a path with a space goes in quotes, and forward slashes work in Java paths, which spares you escaping backslashes in JSON. Every flag is explained in Writing, compiling and running a JavaFX application.

Fix 4: a JDK that includes JavaFX#

Some vendors build a JDK with JavaFX inside, among them BellSoft (the Full JDK package of Liberica JDK) and Azul (the JDK FX package of Zulu). There, JavaFX's modules are part of the runtime, so plain javac HelloApp.java and java HelloApp work with no module path. To check a JDK, run java --list-modules: with JavaFX built in, javafx.controls is in the list. Make sure your IDE runs the program on that JDK too.

The launcher class workaround, and why it is only a workaround#

Many answers online suggest a second main class that does not extend Application:

Start Launcher instead of HelloApp and the error disappears, because java only checks the class it starts. JavaFX is still on the classpath, though, and JavaFX does not support being loaded from there. When it starts, it logs a warning that begins Unsupported JavaFX configuration: classes were loaded from 'unnamed module @, followed by a number that changes on every run. The window usually opens, but on a setup JavaFX does not support, so keep this for the cases that need it, such as one jar that holds every dependency. Fixes 1 to 4 load JavaFX the supported way.

Related errors and what each one means#

Checklist#

1. 1java -version reports 25 or newer, since JavaFX 27 needs JDK 25.
2. 2With Maven or Gradle, the program starts through mvn javafx:run or ./gradlew run, not the Run arrow next to main.
3. 3With the SDK, javac and java both get --module-path pointing at the lib folder and --add-modules naming every JavaFX module you import.
4. 4java also gets --enable-native-access=javafx.graphics.
5. 5In an IDE, the flags sit in the VM options of the run configuration, not in program arguments.