jlink fails with the "automatic module cannot be used with jlink" error

Problem

When building a custom Java runtime image with jlink, the following error occurs:

Error: automatic module cannot be used with jlink: commons.math3

or similar messages for other libraries after adding new dependencies.

This problem may reappear multiple times as jlink identifies additional automatic modules in the project.

Cause

jlink only supports explicit modules, JARs that contain a valid module-info.class descriptor.

However, many third-party libraries such as Apache Commons Math3 are automatic modules. Automatic modules are derived from non-modular JARs that don’t have module-info.java. When jlink encounters one, it fails because it cannot determine explicit module relationships.

Example:

commons-math3-3.6.1.jar → automatic module: commons.math3

Even if you temporarily fix one dependency, new errors can appear as jlink discovers more automatic modules in the dependency graph.

Resolution

Option 1: Use a JDK with JavaFX included

Instead of modularizing every dependency manually, use a JDK that includes JavaFX and supports packaging tools out-of-the-box.

Recommended: BellSoft Liberica Full JDK version 11 or later.

Steps:

1. Install BellSoft Liberica Full JDK. Download it here.
2. In IntelliJ IDEA, set the project SDK to Liberica Full JDK.
3. Rebuild your application.
4. Use jpackage to create the native image instead of jlink.

This resolves most deployment errors and simplifies packaging, as JavaFX modules are already integrated.

Option 2: Convert automatic modules to explicit modules (advanced)

If you must use jlink:

1. Identify all automatic modules:

   java --list-modules
   

2. Replace or rebuild those libraries with modular equivalents.

   • Example: build a modularized version of commons-math3 or switch to a library that includes module-info.java.

3. Update your module-info.java file to explicitly requires those modules.

This approach is more complex and not recommended for most applications.

Workaround

If modularization is too difficult:

• Skip jlink and instead use maven-shade-plugin or jpackage to bundle dependencies into a runnable JAR or native installer.

• For development and testing, you can still run the app via:

  mvn javafx:run