quarkusio/quarkus · error · IllegalStateException

AOT cache generation requires building with JDK 25 or newer

Error message

AOT cache generation requires building with JDK 25 or newer (see JEP 514). 

What it means

Quarkus AOT cache generation (JEP 514, project Leyden premain caching) can only run when the JDK used to BUILD the application is JDK 25 or newer, because the AOT cache tooling (-XX:AOTCache) is only available from JDK 25. createAot checks Runtime.version().feature() and refuses to proceed on older JDKs, since launching the JVM with AOT options would fail or produce no cache.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/pkg/steps/JvmStartupOptimizerArchiveBuildStep.java:330

                command
                        .add(jarResult.getLibraryDir().getParent().resolve(FastJarFormat.QUARKUS_RUN_JAR)
                                .getFileName().toString());
            } else {
                command.add(jarResult.getPath().getFileName().toString());
            }
        }

        return launchArchiveCreateCommand(workingDirectory, appCDSPath, command);
    }

    /**
     * @return The path of the created app.aot file or null if the file was not created
     */
    private Path createAot(JarBuildItem jarResult,
            OutputTargetBuildItem outputTarget, String javaBinPath, String containerImage,
            boolean isFastJar, List<String> additionalRecordingArgs) {
        if (Runtime.version().feature() < 25) {
            throw new IllegalStateException(
                    "AOT cache generation requires building with JDK 25 or newer (see JEP 514). ");
        }
        ArchivePathsContainer aotPathContainers = ArchivePathsContainer.aotFromQuarkusJar(jarResult.getPath());
        return launchArchiveCreateCommand(aotPathContainers.workingDirectory, aotPathContainers.resultingFile,
                createAotCommand(jarResult, outputTarget, javaBinPath, containerImage, isFastJar, additionalRecordingArgs,
                        aotPathContainers));

    }

    private List<String> createAotCommand(JarBuildItem jarResult, OutputTargetBuildItem outputTarget, String javaBinPath,
            String containerImage, boolean isFastJar, List<String> additionalRecordingArgs,
            ArchivePathsContainer aotPathContainers) {
        List<String> javaArgs = new ArrayList<>();
        javaArgs.add("-XX:AOTCacheOutput=" + aotPathContainers.resultingFile.getFileName().toString());
        javaArgs.addAll(additionalRecordingArgs);
        javaArgs.add(String.format("-D%s=true", MainClassBuildStep.GENERATE_APP_CDS_SYSTEM_PROPERTY));
        javaArgs.add("-jar");

View on GitHub (pinned to e1c734241f)

Solutions

1. Set the build to run on JDK 25+ (update JAVA_HOME, maven-toolchains-plugin, or CI setup action to a JDK 25 release)
2. Disable AOT cache generation if JDK 25 is not available (remove quarkus.aot.enabled or the corresponding build flag)
3. Verify with mvn -version / java -version that the JDK performing the build (not just the runtime) is 25+

Example fix

// before (pom.xml, building on JDK 21 with AOT)
<properties>
  <maven.compiler.release>21</maven.compiler.release>
</properties>
// after
<properties>
  <maven.compiler.release>25</maven.compiler.release>
</properties>
<!-- plus run Maven itself on JDK 25: JAVA_HOME=/path/to/jdk-25 -->

int feature = Runtime.version().feature();
if (feature < 25) {
    throw new IllegalStateException("AOT cache requires JDK 25+, found " + feature);
}

When it happens

Trigger: Building with quarkus.aot.enabled=true (or a quarkus:package goal/flag enabling AOT cache generation) while the build JDK's feature version is below 25.

Common situations: CI or developer machines still on JDK 21/17 LTS that enable AOT output; upgrading the project to use the AOT cache feature without upgrading the toolchain JDK.

Related errors

• Failed to open path tree with root %s
• Dev services for ${request.getName()} requires a startable s
• Name cannot start with '/':${name}
• The class (${name}) cannot be created during deployment.
• Use GeneratedServiceProviderBuildItem to register service pr

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