quarkusio/quarkus · error · RuntimeException

Unknown launch mode

Error message

Unknown launch mode 

What it means

AugmentActionImpl's constructor maps a QuarkusBootstrap.Mode to a LaunchMode/DevModeType pair; a mode without an explicit case (i.e. a mode not valid for building an AugmentAction) reaches the default branch and throws this RuntimeException. It means the bootstrap was created with a launch mode that AugmentAction does not support.

Source

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

                break;
            case REMOTE_DEV_CLIENT:
                //this seems a bit counterintuitive, but the remote dev client just keeps a production
                //app up to date and ships it to the remote side, this allows the remote side to be fully
                //up-to-date even if the process is restarted
                launchMode = LaunchMode.NORMAL;
                devModeType = DevModeType.REMOTE_LOCAL_SIDE;
                break;
            case CONTINUOUS_TEST:
                //the process that actually launches the tests is a dev mode process
                launchMode = LaunchMode.DEVELOPMENT;
                devModeType = DevModeType.TEST_ONLY;
                break;
            case REMOTE_DEV_SERVER:
                launchMode = LaunchMode.DEVELOPMENT;
                devModeType = DevModeType.REMOTE_SERVER_SIDE;
                break;
            default:
                throw new RuntimeException("Unknown launch mode " + quarkusBootstrap.getMode());
        }
        this.launchMode = launchMode;
        this.devModeType = devModeType;
    }

    @Override
    public void performCustomBuild(String resultHandler, Object context, String... finalOutputs) {
        try (QuarkusClassLoader classLoader = curatedApplication.createDeploymentClassLoader()) {
            Class<? extends BuildItem>[] targets = Arrays.stream(finalOutputs)
                    .map(new Function<String, Class<? extends BuildItem>>() {
                        @Override
                        public Class<? extends BuildItem> apply(String s) {
                            try {
                                return (Class<? extends BuildItem>) Class.forName(s, false, classLoader);
                            } catch (ClassNotFoundException e) {
                                throw new RuntimeException(e);
                            }
                        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Build the QuarkusBootstrap with LaunchMode.NORMAL for production augmentation, or the documented dev-mode values for dev actions.
2. Inspect quarkusBootstrap.getMode() before creating the AugmentAction and map unsupported modes to NORMAL.
3. If embedding Quarkus, update to a Quarkus version consistent with your bootstrap-mode usage and check AugmentActionImpl for the supported set.
4. In tests, use QuarkusTest/test-specific bootstrap helpers rather than hand-built bootstraps with TEST mode.

Example fix

// before
QuarkusBootstrap.builder(app).setMode(QuarkusBootstrap.Mode.TEST).build().createInitialRuntimeApplication().createAugmentor();
// after
QuarkusBootstrap.builder(app).setMode(QuarkusBootstrap.Mode.PRODUCTION).build().createInitialRuntimeApplication().createAugmentor();

static void requireAugmentableMode(QuarkusBootstrap bootstrap) {
    QuarkusBootstrap.Mode m = bootstrap.getMode();
    if (m == QuarkusBootstrap.Mode.TEST)
        throw new IllegalStateException("AugmentAction does not support mode " + m);
}

try { createAugmentor(); } catch (RuntimeException e) { if (e.getMessage().startsWith("Unknown launch mode")) { /* rebuild bootstrap with NORMAL/PRODUCTION */ } else throw e; }

When it happens

Trigger: Constructing an AugmentAction from a QuarkusBootstrap whose mode is one of the unhandled LaunchMode values (e.g. TEST, DEVELOPMENT variants not explicitly mapped) instead of NORMAL, PRODUCTION, or the explicitly mapped dev modes.

Common situations: Embedding Quarkus augmentation in custom tooling/tests and passing QuarkusBootstrap.Mode.TEST or an unusual mode; IDE runner or custom bootstrap code choosing the wrong mode; Quarkus version changes adding modes not handled by older embedding code.

Related errors

• Can only create a production application when using NORMAL l
• Failed to build Quarkus application for
• Unrecognized option for quarkus.bootstrap.misaligned-platfor
• Failed to prepare injector constructor ${injectCtor} of byte
• Failed to injector constructor ${injectCtor} of bytecode rec

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