quarkusio/quarkus · critical · RuntimeException

Quarkus manual initialization failed

Error message

Quarkus manual initialization failed

What it means

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.

Source

Thrown at core/runtime/src/main/java/io/quarkus/runtime/Quarkus.java:285

            if (tmpState == MANUAL_FAILURE)
                throw new RuntimeException("Quarkus manual bootstrap failed");
            if (tmpState > MANUAL_BEGIN)
                return;
            manualState = MANUAL_BEGIN_INITIALIZATION;
        }

        try {
            // if Application instantiation is removed from manualInit()
            // then Class.forName() should be called for class static initialization of ApplicationImpl
            Class<?> appClass = Class.forName("io.quarkus.runner.ApplicationImpl");
            manualApp = (Application) appClass.getDeclaredConstructor().newInstance();
            manualState = MANUAL_INITIALIZED;
            if (SnapStartRecorder.enabled && SnapStartRecorder.fullWarmup) {
                manualStart();
            }
        } catch (Exception e) {
            manualState = MANUAL_FAILURE;
            throw new RuntimeException("Quarkus manual initialization failed", e);
        }
    }

    /**
     * Manual startup of Quarkus runtime in cases where
     * Quarkus does not have control over main() i.e. Lambda or Azure Functions.
     *
     * This method will call Application.start() and register shutdown hook
     * It will fail if Quarkus.manualInitialize() has not been called.
     *
     *
     */
    public static void manualStart() {
        int tmpState = manualState;
        if (tmpState == MANUAL_FAILURE)
            throw new IllegalStateException("Quarkus failed to start up");
        if (tmpState >= MANUAL_STARTING)
            return;

View on GitHub (pinned to e1c734241f)

Solutions

  1. Read the cause chain of this RuntimeException to find the real failing component.
  2. Fix the underlying configuration or bean error reported in the cause.
  3. Verify all quarkus.* config properties required at runtime are present in the serverless environment.
  4. Rebuild the application so recorder-generated bootstrap code matches the extension versions in use.

Example fix

// before
Quarkus.manualInitialize(); // opaque failure
// after
try { Quarkus.manualInitialize(); } catch (RuntimeException e) { log.error("init failed", e.getCause()); throw e; }
Defensive patterns

Strategy: try-catch

Validate before calling

// validate required quarkus config before init:
ConfigProvider.getConfig().getValue("quarkus.application.name", String.class);

Try / catch

try { Quarkus.manualInitialize(); } catch (RuntimeException e) { Throwable root = e; while (root.getCause() != null) root = root.getCause(); log.error("init root cause", root); throw e; }

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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