quarkusio/quarkus · error · IllegalStateException

Only application with launch mode DEVELOPMENT can restart

Error message

Only application with launch mode DEVELOPMENT can restart

What it means

AugmentActionImpl.reloadExistingApplication() restarts an already-launched dev-mode application after resource/class changes. Restart semantics only exist in DEVELOPMENT mode, so calls in any other launch mode (including TEST) are rejected with this error.

Source

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

    }

    @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,
                    NON_NORMAL_MODE_OUTPUTS);

            return new StartupActionImpl(curatedApplication, result);
        }
    }

    private BuildResult runAugment(boolean firstRun, Set<String> changedResources,
            ClassChangeInformation classChangeInformation, ClassLoader deploymentClassLoader,
            Class<? extends BuildItem>... finalOutputs) {
        ClassLoader old = Thread.currentThread().getContextClassLoader();
        try {
            QuarkusClassLoader classLoader = curatedApplication.getOrCreateAugmentClassLoader();
            Thread.currentThread().setContextClassLoader(classLoader);

View on GitHub (pinned to e1c734241f)

Solutions

1. Ensure the application was originally started via createInitialRuntimeApplication() in LaunchMode.DEVELOPMENT
2. Align the launch mode of your CuratedApplication/AugmentAction with DEVELOPMENT before reloading
3. For tests, use the Quarkus test framework instead of manual reload APIs
4. For production, restart the process rather than calling reload APIs

Example fix

// before
AugmentAction action = curated.createAugmentAction(LaunchMode.TEST);
action.reloadExistingApplication(true, changed, info); // throws
// after
AugmentAction action = curated.createAugmentAction(LaunchMode.DEVELOPMENT);
action.reloadExistingApplication(true, changed, info);

if (launchMode != LaunchMode.DEVELOPMENT) {
    throw new IllegalArgumentException("reloadExistingApplication requires LaunchMode.DEVELOPMENT");
}

try { action.reloadExistingApplication(started, changed, info); } catch (IllegalStateException e) { if (e.getMessage().contains("launch mode DEVELOPMENT")) { /* restart in dev mode */ } else { throw e; } }

When it happens

Trigger: Calling reloadExistingApplication() when the AugmentAction was created with launchMode != LaunchMode.DEVELOPMENT, e.g. a TEST-mode augment action or a NORMAL-mode action, or a dev tool reloading an application launched in a mismatched mode.

Common situations: Custom dev tooling / hot-reload implementations mixing launch modes; quarkus:dev invoking reload against an app bootstrapped with a mismatched mode; test frameworks calling reload APIs.

Related errors

• Hot deployment of the application is not supported when upda
• Unable to perform live reload scanning
• Either location or predicate must be set
• Predicate already set
• Location already set

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