{"record":{"id":"180a9c4fa7f783b7","repo":"quarkusio/quarkus","slug":"quarkus-manual-initialization-failed","errorCode":null,"errorMessage":"Quarkus manual initialization failed","messagePattern":"Quarkus manual initialization failed","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"core/runtime/src/main/java/io/quarkus/runtime/Quarkus.java","lineNumber":285,"sourceCode":"            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) {\n                manualStart();\n            }\n        } catch (Exception e) {\n            manualState = MANUAL_FAILURE;\n            throw new RuntimeException(\"Quarkus manual initialization failed\", e);\n        }\n    }\n\n    /**\n     * Manual startup 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 call Application.start() and register shutdown hook\n     * It will fail if Quarkus.manualInitialize() has not been called.\n     *\n     *\n     */\n    public static void manualStart() {\n        int tmpState = manualState;\n        if (tmpState == MANUAL_FAILURE)\n            throw new IllegalStateException(\"Quarkus failed to start up\");\n        if (tmpState >= MANUAL_STARTING)\n            return;","sourceCodeStart":267,"sourceCodeEnd":303,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/core/runtime/src/main/java/io/quarkus/runtime/Quarkus.java#L267-L303","documentation":"Thrown by Quarkus.manualInitialize() when the actual initialization work (running startup tasks, recorder-produced bootstrap code) throws an Exception. The manual state is set to MANUAL_FAILURE and the original exception is attached as the cause, so the cause is the real diagnostic.","triggerScenarios":"Any Exception escaping the try block in manualInitialize(): a startup task, ConfigProvider, or generated bootstrap code throwing during manual initialization of a Lambda/Azure Functions hosted Quarkus app.","commonSituations":"Missing or invalid configuration in a serverless environment; a CDI bean or StartupEvent observer failing at init; native-image static-init incompatibilities surfacing at first bootstrap in Lambda.","solutions":["Read the cause chain of this RuntimeException to find the real failing component.","Fix the underlying configuration or bean error reported in the cause.","Verify all quarkus.* config properties required at runtime are present in the serverless environment.","Rebuild the application so recorder-generated bootstrap code matches the extension versions in use."],"exampleFix":"// before\nQuarkus.manualInitialize(); // opaque failure\n// after\ntry { Quarkus.manualInitialize(); } catch (RuntimeException e) { log.error(\"init failed\", e.getCause()); throw e; }","handlingStrategy":"try-catch","validationCode":"// validate required quarkus config before init:\nConfigProvider.getConfig().getValue(\"quarkus.application.name\", String.class);","typeGuard":null,"tryCatchPattern":"try { Quarkus.manualInitialize(); } catch (RuntimeException e) { Throwable root = e; while (root.getCause() != null) root = root.getCause(); log.error(\"init root cause\", root); throw e; }","preventionTips":["Verify all required config properties exist in the target environment","Test manual bootstrap locally with the same environment as Lambda/Azure","Keep extensions and Quarkus core versions aligned"],"tags":["quarkus","bootstrap","initialization","wrapped-exception"],"backgroundTag":"quarkus-manual-initialization-failed","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}