quarkusio/quarkus · critical · RuntimeException

Quarkus manual bootstrap failed

Error message

Quarkus manual bootstrap failed

What it means

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.

Source

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

    private static final int MANUAL_BEGIN_INITIALIZATION = 1;
    private static final int MANUAL_INITIALIZED = 2;
    private static final int MANUAL_STARTING = 5;
    private static final int MANUAL_STARTED = 6;
    private static final int MANUAL_FAILURE = 7;
    private static volatile int manualState = MANUAL_BEGIN;
    private static final Object manualLock = new Object();

    /**
     * Manual initialization of Quarkus runtime in cases where
     * Quarkus does not have control over main() i.e. Lambda or Azure Functions.
     *
     * This method will trigger static initialization
     *
     */
    public static void manualInitialize() {
        int tmpState = manualState;
        if (tmpState == MANUAL_FAILURE)
            throw new RuntimeException("Quarkus manual bootstrap failed");
        if (tmpState > MANUAL_BEGIN)
            return;
        synchronized (manualLock) {
            tmpState = manualState;
            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) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Fix the original bootstrap failure: inspect the first exception logged when manualState became MANUAL_FAILURE (bad config, missing dependency, native-image static init error).
2. Run the bootstrap in a fresh JVM; the failure state is process-global and cannot be reset through the public API.
3. Remove retry loops around manualInitialize — a failed manual bootstrap will not succeed on retry within the same process.
4. Ensure only one component calls manualInitialize and handle its exception where the application can react (fail fast).

Example fix

// before: retrying in the same JVM
try { Quarkus.manualInitialize(); } catch (RuntimeException e) { Quarkus.manualInitialize(); } // still fails
// after: fail fast or new JVM
try {
    Quarkus.manualInitialize();
} catch (RuntimeException e) {
    e.printStackTrace();
    System.exit(1); // restart process to retry bootstrap
}

// check bootstrap health before manual init
if (System.getProperty("quarkus.bootstrap.failed") != null) {
    throw new IllegalStateException("Previous manual bootstrap failed; restart the JVM");
}

try {
    Quarkus.manualInitialize();
} catch (RuntimeException e) {
    if ("Quarkus manual bootstrap failed".equals(e.getMessage())) {
        log.error("Static init failed previously; fix root cause and restart the JVM");
        System.exit(1);
    } else throw e;
}

When it happens

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

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

Related errors

• Quarkus already running
• Unrecognized option for quarkus.bootstrap.misaligned-platfor
• All parameters have already been loaded, it is too late to c
• Invalid proxy passed to recorder. ${rp} was created in a run
• Internal error: An attempt was made to start an application

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