quarkusio/quarkus · error · IllegalArgumentException

Application module not found

Error message

Application module  not found

What it means

The launcher creates a ModuleLoader over the image's lib/quarkus directory and calls loadModule(appModule) to load the application module passed as the first argument. A null result means no module descriptor with that name was found in lib/quarkus, so the requested application module does not exist in the image. The appModule name is interpolated into the message.

Source

Thrown at extensions/packaging/jlink/launcher/src/main/java/io/quarkus/jlink/launcher/JLinkAppLauncher.java:67

        }

        Path libPath = imagePath.resolve("lib").resolve("quarkus");

        // create a layer for our dynamic modules
        ModuleLoader dyn = new ModuleLoader("dyn", ModuleFinder.fromFileSystem(List.of(libPath))) {
            public LoadedModule loadModule(final String moduleName) {
                LoadedModule found = base.loadModule(moduleName);
                if (found == null) {
                    found = super.loadModule(moduleName);
                }
                return found;
            }
        };

        // load the application
        LoadedModule loadedModule = dyn.loadModule(appModule);
        if (loadedModule == null) {
            throw new IllegalArgumentException("Application module " + appModule + " not found");
        }

        // set up TCCL; todo: stop relying on this
        Thread.currentThread().setContextClassLoader(loadedModule.classLoader());

        // find the main class
        String mainClassName = loadedModule.module()
                .getDescriptor()
                .mainClass()
                .orElseThrow(() -> new IllegalArgumentException(
                        "Application module " + appModule + " does not have a defined main class"));
        Class<?> mainClass;
        try {
            mainClass = Class.forName(mainClassName, true, loadedModule.classLoader());
        } catch (ClassNotFoundException e) {
            throw sneak(e);
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Check the module name argument matches the module-info name of the application (ls image/lib/quarkus/ to see bundled module jars)
2. Rebuild the jlink image so the current application module is bundled
3. Regenerate the launcher script (it embeds the correct app module name) instead of hand-editing it

Example fix

// before: wrong/stale module name
image/bin/myapp com.example.oldmodule
// after: name matching image/lib/quarkus/com.example.app.jar
image/bin/myapp com.example.app

// verify the app module is bundled before launching
Path libQuarkus = imagePath.resolve("lib").resolve("quarkus");
boolean found;
try (Stream<Path> jars = Files.list(libQuarkus)) {
    found = jars.anyMatch(j -> j.getFileName().toString().equals(appModule + ".jar"));
}
if (!found) throw new IllegalArgumentException("Module not in lib/quarkus: " + appModule);

boolean isModuleBundled(String moduleName, Path libQuarkus) throws IOException {
    try (Stream<Path> jars = Files.list(libQuarkus)) {
        return jars.anyMatch(j -> j.getFileName().toString().equals(moduleName + ".jar"));
    }
}

try {
    JLinkAppLauncher.run(appModule, args);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("not found")) {
        System.err.println("Wrong app module name; check image/lib/quarkus contents");
    }
    throw e;
}

When it happens

Trigger: Running image/bin/<launcher> with an app module name that was not bundled into the image's lib/quarkus directory — wrong module name on the command line, or the image was built without that module.

Common situations: Typos in the module name argument after rebuilding/renaming the application module; stale image from an older build where the module had a different name; manual pruning of lib/quarkus jars.

Related errors

• Must launch jlink image in module mode only
• Module of jlink image launcher is not in a module layer
• You're not expected to use the unnamed module as identifier
• At least one package name must be specified
• The unnamed module cannot be opened to other modules

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/567ad2826eef0ccf. Report an issue: GitHub.