{"record":{"id":"88fda9a684e61409","repo":"quarkusio/quarkus","slug":"quarkus-manual-bootstrap-failed","errorCode":null,"errorMessage":"Quarkus manual bootstrap failed","messagePattern":"Quarkus manual bootstrap failed","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"core/runtime/src/main/java/io/quarkus/runtime/Quarkus.java","lineNumber":262,"sourceCode":"    private static final int MANUAL_BEGIN_INITIALIZATION = 1;\n    private static final int MANUAL_INITIALIZED = 2;\n    private static final int MANUAL_STARTING = 5;\n    private static final int MANUAL_STARTED = 6;\n    private static final int MANUAL_FAILURE = 7;\n    private static volatile int manualState = MANUAL_BEGIN;\n    private static final Object manualLock = new Object();\n\n    /**\n     * Manual initialization of Quarkus runtime in cases where\n     * Quarkus does not have control over main() i.e. Lambda or Azure Functions.\n     *\n     * This method will trigger static initialization\n     *\n     */\n    public static void manualInitialize() {\n        int tmpState = manualState;\n        if (tmpState == MANUAL_FAILURE)\n            throw new RuntimeException(\"Quarkus manual bootstrap failed\");\n        if (tmpState > MANUAL_BEGIN)\n            return;\n        synchronized (manualLock) {\n            tmpState = manualState;\n            if (tmpState == MANUAL_FAILURE)\n                throw new RuntimeException(\"Quarkus manual bootstrap failed\");\n            if (tmpState > MANUAL_BEGIN)\n                return;\n            manualState = MANUAL_BEGIN_INITIALIZATION;\n        }\n\n        try {\n            // if Application instantiation is removed from manualInit()\n            // then Class.forName() should be called for class static initialization of ApplicationImpl\n            Class<?> appClass = Class.forName(\"io.quarkus.runner.ApplicationImpl\");\n            manualApp = (Application) appClass.getDeclaredConstructor().newInstance();\n            manualState = MANUAL_INITIALIZED;\n            if (SnapStartRecorder.enabled && SnapStartRecorder.fullWarmup) {","sourceCodeStart":244,"sourceCodeEnd":280,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/core/runtime/src/main/java/io/quarkus/runtime/Quarkus.java#L244-L280","documentation":"Quarkus.manualInitialize() performs manual static bootstrap of the application and tracks its progress in a manualState field. If a previous manual bootstrap attempt failed, manualState is set to MANUAL_FAILURE, and any subsequent manualInitialize call (checked both before and inside the synchronized block) throws this RuntimeException instead of retrying. It signals that static init already failed and the failure is sticky.","triggerScenarios":"Calling Quarkus.manualInitialize() after an earlier manualInitialize (or static init) in the same JVM threw, leaving manualState == MANUAL_FAILURE; the cached failure is rethrown on every retry.","commonSituations":"Test suites where an earlier bootstrap error (bad config, missing bean) poisoned the singleton state and later tests call manualInitialize again; retry logic around bootstrap that cannot succeed in the same JVM.","solutions":["Fix the original bootstrap failure: inspect the first exception logged when manualState became MANUAL_FAILURE (bad config, missing dependency, native-image static init error).","Run the bootstrap in a fresh JVM; the failure state is process-global and cannot be reset through the public API.","Remove retry loops around manualInitialize — a failed manual bootstrap will not succeed on retry within the same process.","Ensure only one component calls manualInitialize and handle its exception where the application can react (fail fast)."],"exampleFix":"// before: retrying in the same JVM\ntry { Quarkus.manualInitialize(); } catch (RuntimeException e) { Quarkus.manualInitialize(); } // still fails\n// after: fail fast or new JVM\ntry {\n    Quarkus.manualInitialize();\n} catch (RuntimeException e) {\n    e.printStackTrace();\n    System.exit(1); // restart process to retry bootstrap\n}","handlingStrategy":"try-catch","validationCode":"// check bootstrap health before manual init\nif (System.getProperty(\"quarkus.bootstrap.failed\") != null) {\n    throw new IllegalStateException(\"Previous manual bootstrap failed; restart the JVM\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    Quarkus.manualInitialize();\n} catch (RuntimeException e) {\n    if (\"Quarkus manual bootstrap failed\".equals(e.getMessage())) {\n        log.error(\"Static init failed previously; fix root cause and restart the JVM\");\n        System.exit(1);\n    } else throw e;\n}","preventionTips":["Capture and fix the FIRST bootstrap exception — later ones are just the cached failure.","Never retry manualInitialize in the same JVM; it fails permanently.","Validate configuration and beans before triggering manual static init.","Keep manual bootstrap in one place in the codebase with fail-fast handling."],"tags":["quarkus","bootstrap","static-init","lifecycle"],"backgroundTag":"manual-bootstrap-failed","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"}