How to Fix JavaFX’s “Runtime Components are Missing” Error

If you’re not familiar with Java modules, you’re almost guaranteed to get hit with an error: “Runtime Components Are Missing”. It can be a huge frustration if you’re trying to get into JavaFX. Even if you consider yourself to be pretty Java-savvy.

One side effect of Oracle removing JavaFX from the JDK was to make it harder to get started. Honestly, JavaFX should be a very intuitive and easy to use piece of software. But this is one of the few awkward stumbling blocks that trips a lot of people up.

A “Runtime Components are Missing” error is generated by the Java Launcher. It is generated for all non-modular JavaFX projects since Java SE 9. However, it can be corrected by adding JavaFX modules, using command line arguments.

When I first came back to JavaFX after using it in Java 8, every single one of my old prototypes crashed. So if you’ve had this error don’t be disheartened. It’s a relatively easy fix.

How we’re going to fix it

The good news is there are several easy ways to fix your app. Generally, there are two situations you could be in to find this error.

The solutions in each case can be similar, although if you can’t make your app modular you will have to apply command-line arguments both in the IDE and with your Jar.

I’ll start with launching from the IDE, because that seems natural. If you’ve got a Jar that won’t run, feel free to skip on down.

I’ll talk a little about why this is happening, because it has to do with JavaFX’s custom windowing and rendering systems. But, I completely understand if you just need those fixes, you can skip ahead to there too.

Fixing Runtime Components in the short term

This is a wildly irresponsible cowboy fix, but if you’re not looking to a long-term stable project (for example university projects or prototyping), it can be a good way to get around the issue for now.

To jury-rig the Java launch process and fool the LauncherHelper into not realising your app is an instance of a JavaFX Application, you can create a dummy class to act as an entry point to the program.

In this case, we’ll set MyLauncher as the main class for the application and the only responsibility of this class will be to launch our actual application!

package com.edencoding;
public class MyLauncher {
    public static void main(String[] args){
        MyApp.main(args);
    }
}

The benefit of this fix is that it will get rid of this error in both the IDE and with a packaged Jar. That being said, I’d really recommend checking out some of the more sustainable fixes below.

Especially in the case of an app you want to deploy in a production environment, you’ll have a much bigger job changing your application when it’s already in production.

If you’re curious as to why JavaFX needs to check that the runtime components are present, check out the drop-down below.

Why JavaFX needs ‘Runtime Components’

Java has other windowing solutions that don’t need this custom support, so why does JavaFX? Well, the Abstract Window Toolkit (AWT) has been with Java since the beginning. In that sense, it’s baked into the Java runtime. Swing, which also provides a GUI framework, is sat on top of AWT.

Swing, JavaFX uses its own custom windowing toolkit – glass – which is used in combination with prism, its graphics engine. Both of these are inside the javafx.graphics module. When JavaFX was added, the Java launcher was modified to allow JavaFX to set itself up before the application launched.

This is done inside a class called LauncherHelper, which is called whenever any class or jar is run.

As with everything in Java, it also makes sense to delegate where you can. So, when an application is launched, LauncherHelper checks whether it’s a JavaFX program, and if it is, it hands off the responsibilities to the FXLauncher, which runs some pre-flight checks and sets itself up ready to run.

In fact, the main class that the FXLauncher launches isn’t the main class of your application. In this case, FXHelper does the any setup needed before checking back in with our app.

One fix I’ll go through today short-circuits this test by jury-rigging the launch process to fool Java into thinking it’s not a JavaFX application. For small projects, that’s OK, but if you’re looking at developing a production-level or portfolio app, there are other, more sensible ways to do this.

If you’re looking for a really fast fix, though, it does the job.

Fixing JavaFX Runtime Components Issues Responsibly

A lot of these fixes aren’t a lot harder than the cowboy fix above, but they do take a little bit of understanding, or a tiny bit of patience.

in the first case, converting to modules takes a litte bit of understanding. But it’s a fix that will work in both the IDE and the Jar. If you choose to provide VM arguments manually, you’re going to need to provide these to run the Jar too – hence the patience.

1. Make your app modular

By far and away the most future-proof way to fix this error is to convert your project over to a modular one. That being said, it’s not always practical. There are plenty of libraries that currently don’t fully support java 9 modules (Apache POI is a great example)

It can also be a little intimidating if you haven’t migrated yourself across to modular projects yet.

The price you pay for shedding up to 150 MB off the program you’ll eventually ship is that you need to specify which modules your program requires. If there isn’t an overwhelming reason why you need to stay pre-modular, I would suggest the a few lines of code (5 in this case) is more than worth it.

Adding modules

There are three things you need to add some basic modules to a simple App. Obviously, the modules you need will be guided by the modules you use in your program, but the three basic rules are:

1. Getting access to other modules

Some modules use the transitive keyword to specify modules that they need, but also that you have access to as well! A good example of this is the javafx.controls module, which requires transitive javafx.graphics and javafx.base. That means your program can access javafx.graphics and javafx.base but you don’t need to include module statements for them.

If course, if you’re not using a build framework, you will still need to download the javafx.graphics and javafx.base jars or jmods for your program to work.

2. Giving reflective access to your module

The JavaFX graphics module injects fields into a Controller using reflection. This is useful, because it facilitates dependency injection, but it means we need to grant reflective access. That requires the opens keyword.

3. Giving other access to your module

Part of that process is that the FXLauncher operates on our main class in order to launch it (check out “Why JavaFX needs Runtime Components” in the dropdown above), we need to allow that too.

3. Putting it all together

All-in-all, our module-info.java file should be in the root of our project directory and for a module called my.project, should look like this:

module my.project {
    requires javafx.fxml;
    requires javafx.controls;
    opens my.project to javafx.graphics;
    exports my.project;
}

That’s all we need. If you want more detail on adding modules to a project, check out my post on setting up a modular project with Maven.

Honestly, Java’s module system means that Java is now purpose-built to do things like add in JavaFX. For me this is the logical way to fix the project.

2. Add command-line arguments to your app

This is a pretty flexible fix, which can be done in any IDE. The caveat is that you’ll also need to provide the same arguments when running your Jar. For this to work, you’ll need to know the location of the JavaFX SDK you’ve downloaded on your machine.

I’ll go through what the parameters are first, then how to add them to your IDE. Finally, we’ll cover how to add these arguments when running your jar.

The module parameters you need to add

To fix this, we’re going to pass two sets of parameters to Java as we run our code.

1. Module Path

The first is --module-path, which is going to specify the location in our filesystem where the JavaFX jars are located. Regardless of where you’ve located it, you need to provide the address to the lib folder (this is where the jars are stored).

--module-path /path/to/javafx-sdk-14/lib

2. Modules to add

The second argument is --add-modules. This will define which modules to add to our project. For the simplest project, you’ll just need javafx.graphics. However, the basic use-case of an app with buttons (controls), FXML files and so on will require we include javafx.controls and javafx.fxml. Include these separated by a comma but no space.

--add-modules javafx.controls,javafx.fxml

Make sure you leave a space between the --module-path arguments and the --add-modules arguments or you’ll continue to see errors..

--module-path /path/to/javafx-sdk-14/lib --add-modules javafx.controls,javafx.fxml

Next, we’ll add them into the IDE run configuration.

Adding VM arguments in an IDE

The most popular are Eclipse and IntelliJ, so I’ll include some screenshots here, but this should work no matter which environment you’re developing in.

a. Eclipse

To add VM arguments in Eclipse, right click the project. Click Run as then Run Configurations. Head to the the Arguments tab and you’ll want the VM Arguments box (not the program arguments one).

b. IntelliJ

In IntelliJ, click the drop-down to the left of the run button, or in the menu bar, Run -> Edit Configurations. In the right-hand panel of your run configuration, specify your main class, and add VM options in the box below.

And that’s it! Your program should run in the IDE.

Adding VM arguments to a Jar

If dependencies or project-constraints are stopping you from converting your project to a modular structure and rebuilding your Jar, you can still run your jar using a batch (or shell) script providing the runtime arguments to the launcher.

Batch scripts allow you to save executable commands into a plain text file to run later. What we’ll save is a combination of the java command to launch a jar (java -jar myJar.jar) with the arguments needed to specify the runtime components. So in each case, our script will run:

java -jar myJar.jar --module-path /path/to/javafx-sdk-14/lib --add-modules javafx.controls,javafx.fxml

If you don’t know how to create these files, here’s how. I’ll run through how to create both batch and shell scripts on Windows and Mac/Unix systems. In either case, we’ll be running the same command.

1. Creating a batch file

In Windows, create a file labelled launcher.bat in the same directory as your Jar file. Right click and select “edit” to edit your file.

Add the text, editing your module path so it points to the lib folder of the JavaFX SDK you have on your system, and save.