quarkusio/quarkus · error · IllegalStateException

Cannot launch a runtime application with NORMAL launch mode

Error message

Cannot launch a runtime application with NORMAL launch mode

What it means

AugmentActionImpl.createInitialRuntimeApplication() prepares a live, restartable runtime application for dev tooling. It is only valid in non-NORMAL launch modes; in NORMAL (production) mode the framework refuses so production augmentation is never misused to launch a mutable runtime app.

Source

Thrown at core/deployment/src/main/java/io/quarkus/runner/bootstrap/AugmentActionImpl.java:343

            // least priority
            if (type.equals("appCDS")) {
                return 0;
            }

            // default
            return 10;
        }
    }

    private static String artifactPathForResultMetadata(BuildSystemTargetBuildItem outputTargetBuildItem,
            ArtifactResultBuildItem artifactResultBuildItem) {
        return outputTargetBuildItem.getOutputDirectory().relativize(artifactResultBuildItem.getPath()).toString();
    }

    @Override
    public StartupActionImpl createInitialRuntimeApplication() {
        if (launchMode == LaunchMode.NORMAL) {
            throw new IllegalStateException("Cannot launch a runtime application with NORMAL launch mode");
        }
        try (QuarkusClassLoader classLoader = curatedApplication.createDeploymentClassLoader()) {
            @SuppressWarnings("unchecked")
            BuildResult result = runAugment(true, Collections.emptySet(), null, classLoader, NON_NORMAL_MODE_OUTPUTS);
            return new StartupActionImpl(curatedApplication, result);
        }
    }

    @Override
    public StartupActionImpl reloadExistingApplication(boolean hasStartedSuccessfully, Set<String> changedResources,
            ClassChangeInformation classChangeInformation) {
        if (launchMode != LaunchMode.DEVELOPMENT) {
            throw new IllegalStateException("Only application with launch mode DEVELOPMENT can restart");
        }

        try (QuarkusClassLoader classLoader = curatedApplication.createDeploymentClassLoader()) {
            @SuppressWarnings("unchecked")
            BuildResult result = runAugment(!hasStartedSuccessfully, changedResources, classChangeInformation, classLoader,

View on GitHub (pinned to e1c734241f)

Solutions

Create the CuratedApplication/AugmentAction with LaunchMode.DEVELOPMENT or TEST
Use the standard production entry point (io.quarkus.runtime.Quarkus.run) instead of dev bootstrap APIs
Check the launch-mode supplier wired into your bootstrap code

Example fix

// before
CuratedApplication app = curator.bootstrap();
AugmentAction action = app.createAugmentAction(); // launchMode defaults to NORMAL
// after
CuratedApplication app = curator.bootstrap();
AugmentAction action = app.createAugmentAction(LaunchMode.DEVELOPMENT);

Defensive patterns

Strategy: validation

Validate before calling

if (launchMode == LaunchMode.NORMAL) {
    throw new IllegalArgumentException("createInitialRuntimeApplication requires DEVELOPMENT or TEST mode");
}

Try / catch

try { action.createInitialRuntimeApplication(); } catch (IllegalStateException e) { if (e.getMessage().contains("NORMAL launch mode")) { /* recreate action in dev/test mode */ } else { throw e; } }

Prevention

Always pass an explicit LaunchMode when bootstrapping CuratedApplication
Never call dev bootstrap APIs from production entry points
Use Quarkus.run() for production launches

When it happens

Trigger: Calling createInitialRuntimeApplication() (or creating a CuratedApplication and its AugmentAction) when launchMode is LaunchMode.NORMAL, e.g. invoking dev-mode bootstrap APIs from production code or tests using the default launch mode.

Common situations: Dev tools or test harnesses constructing AugmentAction manually without setting LaunchMode.DEVELOPMENT/TEST; embedding Quarkus bootstrapping in application code that runs in production mode.

Related errors

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