quarkusio/quarkus · critical · IllegalStateException

Unable to determine launch jar path

Error message

Unable to determine launch jar path

What it means

AotQuarkusEntryPoint.doRun() launches an AOT-packaged Quarkus application. It determines the location of the runner jar via QuarkusEntryPoint.resolveJarPath(AotQuarkusEntryPoint.class); if the protection domain/code source yields null it cannot locate the launch jar and throws IllegalStateException. This indicates the entry point is not running from a jar as expected.

Source

Thrown at independent-projects/bootstrap/runner/src/main/java/io/quarkus/bootstrap/runner/AotQuarkusEntryPoint.java:45

        System.setProperty("java.util.concurrent.ForkJoinPool.common.threadFactory",
                "io.quarkus.bootstrap.forkjoin.QuarkusForkJoinWorkerThreadFactory");
        Timing.staticInitStarted(false);

        try {
            doRun(args);
        } catch (RuntimeException | Error e) {
            InitialConfigurator.DELAYED_HANDLER.close();
            throw e;
        } catch (Throwable t) {
            InitialConfigurator.DELAYED_HANDLER.close();
            throw new UndeclaredThrowableException(t);
        }
    }

    private static void doRun(String... args) throws Throwable {
        Path jarPath = QuarkusEntryPoint.resolveJarPath(AotQuarkusEntryPoint.class);
        if (jarPath == null) {
            throw new IllegalStateException("Unable to determine launch jar path");
        }
        Path appRoot = jarPath.getParent().getParent().getParent();

        // Load cached resources and main class name
        AotSerializedApplication app;
        Path cacheFile = appRoot.resolve(QUARKUS_APPLICATION_DAT);
        if (Files.isReadable(cacheFile)) {
            try (InputStream in = new BufferedInputStream(Files.newInputStream(cacheFile), 8192)) {
                app = AotSerializedApplication.read(in);
            }
        } else {
            throw new IllegalStateException("Serialized application file not found or not readable: " + cacheFile
                    + ". The application may not have been packaged correctly with aot-jar type.");
        }

        final AotRunnerClassLoader aotRunnerClassLoader = app.getRunnerClassLoader();
        try {
            Thread.currentThread().setContextClassLoader(aotRunnerClassLoader);

View on GitHub (pinned to e1c734241f)

Solutions

1. Launch the application with the generated Quarkus runner jar (java -jar target/quarkus-app/quarkus-run.jar) rather than a custom classpath.
2. Rebuild the package with the aot-jar packaging type (mvn package) so the runner layout is correct.
3. Do not run AotQuarkusEntryPoint from exploded target/classes in an IDE; use the packaged artifact.

Example fix

// before
java -cp target/classes:libs/* io.quarkus.bootstrap.runner.AotQuarkusEntryPoint

// after
java -jar target/quarkus-app/quarkus-run.jar

Path runner = Paths.get(System.getProperty("java.class.path").split(File.pathSeparator)[0]);
if (!runner.toString().endsWith(".jar")) {
    throw new IllegalStateException("Launch with the Quarkus runner jar, not exploded classes");
}

try {
    AotQuarkusEntryPoint.main(args);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Unable to determine launch jar path")) {
        System.err.println("Run via: java -jar target/quarkus-app/quarkus-run.jar");
    } else throw e;
}

When it happens

Trigger: Running the AOT entry point (java -cp ... io.quarkus.bootstrap.runner.AotQuarkusEntryPoint) from a classes directory, shaded/unusual jar layout, or a custom launcher where resolveJarPath() returns null instead of a jar path.

Common situations: Launching the AOT application with a hand-written classpath instead of the generated runner jar, running from an IDE with exploded classes, or repackaging the runner jar in a way that breaks code-source resolution.

Related errors

• Serialized application file not found or not readable: ${cac
• Invalid magic number in AOT cache file: expected 0x${MAGIC}
• Unsupported AOT cache version: expected ${VERSION} but got $
• remote-dev can only be used with mutable applications i.e. u
• Unknown JAR package type '${value}'

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