quarkusio/quarkus · critical · IllegalStateException

Quarkus applications require Java 21 or higher to build

Error message

Quarkus applications require Java 21 or higher to build

What it means

Quarkus augmentation requires at least Java 21; QuarkusAugmentor.run() checks Runtime.version().feature() before building and throws IllegalStateException on older JDKs. The framework itself is compiled for Java 21, so building an app with an older JVM cannot proceed.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/QuarkusAugmentor.java:103

        this.targetDir = builder.targetDir;
        this.effectiveModel = builder.effectiveModel;
        this.baseName = builder.baseName;
        this.originalBaseName = builder.originalBaseName;
        this.deploymentClassLoader = builder.deploymentClassLoader;
        this.rebuild = builder.rebuild;
        this.devModeType = builder.devModeType;
        this.auxiliaryApplication = builder.auxiliaryApplication;
        this.auxiliaryDevModeType = Optional.ofNullable(builder.auxiliaryDevModeType);
        this.test = builder.test;
        this.depInfoProvider = builder.depInfoProvider;
        if (this.baseName != null) {
            this.buildSystemProperties.put("quarkus.build.base-name", baseName);
        }
    }

    public BuildResult run() throws Exception {
        if (!(Runtime.version().feature() >= 21)) {
            throw new IllegalStateException("Quarkus applications require Java 21 or higher to build");
        }
        long start = System.nanoTime();
        log.debug("Beginning Quarkus augmentation");
        runtimeInitializeForAugmentation();
        ClassLoader originalClassLoader = Thread.currentThread().getContextClassLoader();
        try (QuarkusBuildCloseablesBuildItem buildCloseables = new QuarkusBuildCloseablesBuildItem()) {
            Thread.currentThread().setContextClassLoader(deploymentClassLoader);

            BuildChainBuilder chainBuilder = BuildChain.builder();
            chainBuilder.setClassLoader(deploymentClassLoader);

            ExtensionLoader.loadStepsFrom(deploymentClassLoader, buildSystemProperties, runtimeProperties, effectiveModel,
                    launchMode, devModeType).accept(chainBuilder);

            Thread.currentThread().setContextClassLoader(classLoader);
            chainBuilder.loadProviders(classLoader);

            chainBuilder.addPriorityItem(LoggingSetupBuildItem.class);

View on GitHub (pinned to e1c734241f)

Solutions

1. Install JDK 21+ and set JAVA_HOME to it (e.g. export JAVA_HOME=/path/to/jdk-21).
2. In the IDE, set the project/Gradle/Maven JVM to 21+.
3. In CI, update the setup-java action or container image to JDK 21 (e.g. temurin:21).

Example fix

// before (CI)
java-version: '17'
// after
java-version: '21'

if (Runtime.version().feature() < 21) {
    throw new IllegalStateException("Java 21+ is required; current JDK: " + Runtime.version());
}

static boolean isJava21Plus() {
    return Runtime.version().feature() >= 21;
}

When it happens

Trigger: Running ./mvnw quarkus:build, quarkus:dev, or a test that invokes QuarkusAugmentor with JAVA_HOME pointing to a JDK older than 21.

Common situations: CI runner with an outdated default JDK; IDE configured with an old project JDK; JAVA_HOME pointing to JDK 17 after upgrading Quarkus (which raised the minimum from 17 to 21).

Related errors

• No system java compiler provided
• Failed to redefine module ${moduleName}
• Failed to acquire handle to Module#implAddOpens. This must b
• Failed to invoke implAddOpens
• The '@Version' annotation cannot be used on primitive types.

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