{"record":{"id":"a46e297c6eda5eb7","repo":"quarkusio/quarkus","slug":"unable-to-determine-launch-jar-path-a46e29","errorCode":null,"errorMessage":"Unable to determine launch jar path","messagePattern":"Unable to determine launch jar path","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"independent-projects/bootstrap/runner/src/main/java/io/quarkus/bootstrap/runner/QuarkusEntryPoint.java","lineNumber":49,"sourceCode":"        System.setProperty(\"java.util.concurrent.ForkJoinPool.common.threadFactory\",\n                \"io.quarkus.bootstrap.forkjoin.QuarkusForkJoinWorkerThreadFactory\");\n        Timing.staticInitStarted(false);\n\n        try {\n            doRun(args);\n        } catch (RuntimeException | Error e) {\n            InitialConfigurator.DELAYED_HANDLER.close();\n            throw e;\n        } catch (Throwable t) {\n            InitialConfigurator.DELAYED_HANDLER.close();\n            throw new UndeclaredThrowableException(t);\n        }\n    }\n\n    private static void doRun(String... args) throws Throwable {\n        Path jarPath = resolveJarPath(QuarkusEntryPoint.class);\n        if (jarPath == null) {\n            throw new IllegalStateException(\"Unable to determine launch jar path\");\n        }\n        Path appRoot = jarPath.getParent().getParent().getParent();\n\n        if (Boolean.parseBoolean(System.getenv(\"QUARKUS_LAUNCH_DEVMODE\"))) {\n            DevModeMediator.doDevMode(appRoot);\n        } else if (Boolean.getBoolean(\"quarkus.launch.rebuild\")) {\n            doReaugment(appRoot);\n        } else {\n            SerializedApplication app;\n            // the magic number here is close to the smallest possible dat file\n            try (InputStream in = new BufferedInputStream(Files.newInputStream(appRoot.resolve(QUARKUS_APPLICATION_DAT)),\n                    24_576)) {\n                app = SerializedApplication.read(in, appRoot);\n            }\n            final RunnerClassLoader appRunnerClassLoader = app.getRunnerClassLoader();\n            try {\n                Thread.currentThread().setContextClassLoader(appRunnerClassLoader);\n                QuarkusForkJoinWorkerThread.setQuarkusAppClassloader(appRunnerClassLoader);","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/independent-projects/bootstrap/runner/src/main/java/io/quarkus/bootstrap/runner/QuarkusEntryPoint.java#L31-L67","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Launch via the generated quarkus-run script (java -jar target/quarkus-app/quarkus-run.jar) instead of manual classpaths.","Verify the standard layout exists: <appRoot>/app|lib|quarkus-run.jar with the launcher jar under lib/.","Do not extract or relocate QuarkusEntryPoint.class out of its jar.","Ensure the running QuarkusEntryPoint is the one from quarkus-bootstrap-runner in your build, not a stray older jar."],"exampleFix":"// before\njava -cp 'quarkus-app/*' io.quarkus.bootstrap.runner.QuarkusEntryPoint\n// after\njava -jar target/quarkus-app/quarkus-run.jar","handlingStrategy":"validation","validationCode":"Path launcher = appRoot.resolve(\"quarkus-run.jar\");\nif (!Files.isRegularFile(launcher)) throw new IllegalStateException(\"missing quarkus-run.jar — use the generated run script or java -jar quarkus-run.jar\");","typeGuard":"boolean hasStandardLayout(Path appRoot) { return Files.isRegularFile(appRoot.resolve(\"quarkus-run.jar\")) && Files.isDirectory(appRoot.resolve(\"lib\")); }","tryCatchPattern":"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; }","preventionTips":["Always start via the generated quarkus-run script or quarkus-run.jar.","Never extract the runner jars from quarkus-app.","Preserve the quarkus-app directory structure when copying.","Keep the launcher jar in lib/ alongside bootstrap-runner."],"tags":["startup","launcher","classpath"],"backgroundTag":"missing-launch-artifact","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}