jlink "Error: module not found" - Fix in CI

jlink assembles a custom runtime image from explicit modules and could not find one it was told to include. Either the module is missing from the --module-path, or it is an automatic module (a plain jar) that jlink cannot link.

What this error means

The jlink step fails with Error: module not found: com.example.app or Error: automatic module cannot be used with jlink: gson from file:.... No runtime image is produced.

Error: module not found: com.example.app

# or, for a plain jar:
Error: automatic module cannot be used with jlink: gson from
file:///work/libs/gson-2.11.0.jar

Common causes

Module missing from the module path

A module named in --add-modules (or required transitively) is not on --module-path, so jlink cannot locate it.

A dependency is an automatic module

jlink only links explicit modules (with module-info); a plain jar treated as an automatic module cannot be included.

Wrong module names in the link command

The --add-modules list uses jar names or stale names that do not match the real module names.

How to fix it

Put every required module on the module path

Include all transitive modules in --module-path.

jlink --module-path "$JAVA_HOME/jmods:target/modules" \
  --add-modules com.example.app \
  --output target/runtime

Replace automatic modules with real modules

Use a modularized version of the dependency, or generate a module descriptor, so jlink can link it.

# verify a jar is a real module (has module-info), not automatic
jar --describe-module --file gson-2.11.0.jar

Use correct module names

List the actual module names jlink expects.

jar --describe-module --file target/app.jar   # confirm the name

How to prevent it

• Provide the full transitive module set on --module-path.
• Use fully modularized dependencies for jlink images.
• Resolve names with jar --describe-module before listing --add-modules.

Related guides