quarkusio/quarkus · error · BuildException

Build failed during jlink (exit code )

Error message

Build failed during jlink (exit code )

What it means

The jlink tool invoked by JLinkSteps.jlink returned a non-zero exit code, so the image could not be produced. The step wraps the raw jlink failure in a Quarkus BuildException with the exit code. The underlying reason is in the log output emitted just above via LogWriter.

Source

Thrown at extensions/packaging/jlink/deployment/src/main/java/io/quarkus/jlink/deployment/JLinkSteps.java:252

                stagedOutput.bootModulePath().values().stream().map(Path::toString).toArray(String[]::new)));

        // todo: include the whole boot path until --bind-services works
        jlinkArgs.add("--add-modules");
        jlinkArgs.add(addedModules);

        // everything looks good; make the directory for the image output
        Files.createDirectories(imagePath.getParent());
        log.info("Building image with jlink");
        log.debugf("JLink arguments: %s", String.join("\n\t", jlinkArgs));
        Instant start = Instant.now();
        int result = jlinkProvider.run(
                new PrintWriter(new LogWriter(jlinkOut, Logger.Level.INFO)),
                new PrintWriter(new LogWriter(jlinkOut, Logger.Level.WARN)),
                jlinkArgs.toArray(String[]::new));
        Instant end = Instant.now();
        Duration duration = end.compareTo(start) < 0 ? Duration.ZERO : Duration.between(start, end);
        if (result != 0) {
            throw new BuildException("Build failed during jlink (exit code " + result + ")");
        }
        // produce the dynamic lib files
        // bundle dynamic modules into the image
        Path lib = config.outputDirectory().resolve(config.imagePath()).resolve("lib").resolve("quarkus");
        Files.createDirectories(lib);
        final AppModuleModel model = moduleInfoItem.model();
        Map<String, ModuleInfo> modulesByName = model.modulesByName();
        for (ModuleInfo moduleInfo : modulesByName.values()) {
            String moduleName = moduleInfo.name();
            if (model.bootModules().contains(moduleName)) {
                // skip boot modules
                continue;
            }
            // TODO: create an actual manifest (if needed)
            ModuleWriter.writeModule(moduleInfo, lib.resolve(moduleInfo.name()), new Manifest(), false);
        }

        log.infof("JLink image produced in %s at %s; to run the image, execute %s in that directory",

View on GitHub (pinned to e1c734241f)

Solutions

1. Read the jlink INFO/WARN log lines printed immediately before the exception for the real cause
2. Verify all modules referenced (including app modules and JDK modules) resolve — run `jlink` manually with the same args to reproduce
3. Remove duplicate module artifacts from the dependency tree (mvn dependency:tree)
4. Ensure a full JDK (not JRE) is used and there is adequate disk space in the output directory
5. Clean build to rule out stale generated module-info files

Example fix

// before: module referenced in config is not on module path
quarkus.jlink.add-modules java.sql,com.example.nonexistent
// after
quarkus.jlink.add-modules java.sql,com.example.app

// pre-validate modules referenced by jlink config exist on the module path
for (String m : jlinkConfig.addModules()) {
    ModuleFinder mf = ModuleFinder.of(modulePathEntries);
    if (mf.find(m).isEmpty()) {
        throw new IllegalArgumentException("Module not on module path: " + m);
    }
}

try {
    jlink(config, moduleInfoItem, ...);
} catch (BuildException e) {
    // jlink logs the root cause at INFO/WARN just before this; surface it
    throw new IllegalStateException("jlink failed; see jlink log output above for the real cause", e);
}

When it happens

Trigger: The external jlink command (JLink) exits non-zero, e.g. due to missing modules, duplicate/invalid module descriptors, bad --add-modules/launcher options, or insufficient disk space.

Common situations: Referencing modules not present in the JDK/module path; split packages across modules; invalid image name or output paths; running on a JRE without jlink; corrupted Maven/incremental state.

Related errors

• Failed to build enhanced artifact
• Boot module listed in model is missing from the module index
• ${archiveRoot} does not point to the application output dire
• service interface name cannot be null or blank
• service interface descriptor file path cannot be null

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