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.

  • You’re in an IDE and when you hit ‘Run’ the IDE delivers the error
  • You’ve got a JavaFX application packaged as a jar. It won’t run, but you’re smart enough to run it from the command line. Low and behold… 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.

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
  • Whenever you want to include a module in your program, you need to use the requires keyword

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
  • We need to give javafx.graphics reflective access.

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 the process of launching our app is to allow JavaFX to set up quickly int he background and then call our main class when it’s ready. To allow this, we need the exports keyword.

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).

VM Arguments can be added in the Eclipse IDE to fix the JavaFX's Runtime Components Are Missing error
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.

VM Arguments can be added in the IntelliJ IDE to fix the JavaFX's Runtime Components Are Missing error

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. 👍

To launch your application, simply double-click the script file, or launch it from the terminal.

2. Creating a shell file

In Linux or on Mac, launch the terminal and navigate to the folder with your jar, and create a file using the command "touch launchScript“.

Using your favourite text editor, we’ll need to add two commands to the file. The first directs the system to run launchScript as a shell script, and the second runs our app with the VM arguments.

#!/bin/bash

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

Again, edit your module path so it points to the lib folder of the JavaFX SDK you have on your system, and save. In the same way as with Windows, to launch your application, simply double-click the script file, or launch it from the terminal.

Conclusions

A “Runtime Components are Missing” error is generated by the Java launcher if JavaFX is unable to set up ahead of launching your app. This is required by the Java Launcher, which requires JavaFX to be on the module path in order to confirm the runtime requirements are met prior to launching.

We can solve this error by modifying our project to make it modular, and adding the correct JavaFX modules. However, if project constraints prevent you from modularising your project, these arguments can also be provided manually.

Inside an IDE, arguments can be passed to the virtual machine through the VM options settings in Run Configurations. Once packaged as a Jar, these settings much be set manually each time we want to launch the Jar. This can be automated by creating script files that are responsible for launching our app.