quarkusio/quarkus · critical · IllegalStateException

Unable to determine launch jar path

Error message

Unable to determine launch jar path

What it means

An IllegalStateException from QuarkusEntryPoint.doRun when resolveJarPath(QuarkusEntryPoint.class) returns null — i.e. the runner cannot determine which jar the entry point class was loaded from, so the application root directory cannot be derived. The app was not launched in the layout the runner expects.

Source

Thrown at independent-projects/bootstrap/runner/src/main/java/io/quarkus/bootstrap/runner/QuarkusEntryPoint.java:49

        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 = resolveJarPath(QuarkusEntryPoint.class);
        if (jarPath == null) {
            throw new IllegalStateException("Unable to determine launch jar path");
        }
        Path appRoot = jarPath.getParent().getParent().getParent();

        if (Boolean.parseBoolean(System.getenv("QUARKUS_LAUNCH_DEVMODE"))) {
            DevModeMediator.doDevMode(appRoot);
        } else if (Boolean.getBoolean("quarkus.launch.rebuild")) {
            doReaugment(appRoot);
        } else {
            SerializedApplication app;
            // the magic number here is close to the smallest possible dat file
            try (InputStream in = new BufferedInputStream(Files.newInputStream(appRoot.resolve(QUARKUS_APPLICATION_DAT)),
                    24_576)) {
                app = SerializedApplication.read(in, appRoot);
            }
            final RunnerClassLoader appRunnerClassLoader = app.getRunnerClassLoader();
            try {
                Thread.currentThread().setContextClassLoader(appRunnerClassLoader);
                QuarkusForkJoinWorkerThread.setQuarkusAppClassloader(appRunnerClassLoader);

View on GitHub (pinned to e1c734241f)

Solutions

1. Launch via the generated quarkus-run script (java -jar target/quarkus-app/quarkus-run.jar) instead of manual classpaths.
2. Verify the standard layout exists: <appRoot>/app|lib|quarkus-run.jar with the launcher jar under lib/.
3. Do not extract or relocate QuarkusEntryPoint.class out of its jar.
4. Ensure the running QuarkusEntryPoint is the one from quarkus-bootstrap-runner in your build, not a stray older jar.

Example fix

// before
java -cp 'quarkus-app/*' io.quarkus.bootstrap.runner.QuarkusEntryPoint
// after
java -jar target/quarkus-app/quarkus-run.jar

Path launcher = appRoot.resolve("quarkus-run.jar");
if (!Files.isRegularFile(launcher)) throw new IllegalStateException("missing quarkus-run.jar — use the generated run script or java -jar quarkus-run.jar");

boolean hasStandardLayout(Path appRoot) { return Files.isRegularFile(appRoot.resolve("quarkus-run.jar")) && Files.isDirectory(appRoot.resolve("lib")); }

try { app.start(); } catch (IllegalStateException e) { if ("Unable to determine launch jar path".equals(e.getMessage())) { log.error("QuarkusEntryPoint launched without its jar in the standard app layout"); throw new IllegalStateException("Run via quarkus-run.jar / quarkus-run script", e); } throw e; }

When it happens

Trigger: Launching QuarkusEntryPoint in a way where its class is not loaded from a jar inside the expected quarkus-app directory tree (e.g. extracted classes dir, custom classloader, missing launcher jar, or running the wrong class directly).

Common situations: Unzipping quarkus-app and running classes manually instead of the run script; moving/removing the launcher jar; running with -cp of unpacked classes; packaging without the standard quarkus-app directory layout.

Related errors

• Expected : after attribute
• Failed to load CodeGenProvider class from deployment classlo
• Failed to read %s
• Failed to read resources from classpath
• Could not read class path resources having path '${resourceP

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