{"record":{"id":"a10c6ca7f5dea429","repo":"oracle/graal","slug":"configuration-specified-a-java-version-incompatibl","errorCode":null,"errorMessage":"Configuration specified a Java version incompatible with the pre-initialized language - expected: %s, got: %s.","messagePattern":"Configuration specified a Java version incompatible with the pre-initialized language - expected: (.+?), got: (.+?)\\.","errorType":"exception","errorClass":"ContextPatchingException","httpStatus":null,"severity":"error","filePath":"espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/preinit/ContextPatchingException.java","lineNumber":36,"sourceCode":" *\n * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA\n * or visit www.oracle.com if you need additional information or have any\n * questions.\n */\npackage com.oracle.truffle.espresso.preinit;\n\nimport com.oracle.truffle.api.CompilerAsserts;\nimport com.oracle.truffle.espresso.classfile.JavaVersion;\n\npublic final class ContextPatchingException extends Exception {\n\n    private static final long serialVersionUID = -762795124477419520L;\n\n    public static ContextPatchingException javaVersionMismatch(JavaVersion languageJavaVersion, JavaVersion contextJavaVersion) throws ContextPatchingException {\n        CompilerAsserts.neverPartOfCompilation();\n        String errMsg = String.format(\"Configuration specified a Java version incompatible with the pre-initialized language - expected: %s, got: %s.\", languageJavaVersion,\n                        contextJavaVersion);\n        throw new ContextPatchingException(errMsg);\n    }\n\n    private ContextPatchingException(String message) {\n        super(message);\n    }\n}\n","sourceCodeStart":18,"sourceCodeEnd":43,"githubUrl":"https://github.com/oracle/graal/blob/a66e9ccd1d7bf2552883939aa0788dfd0e294aab/espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/preinit/ContextPatchingException.java#L18-L43","documentation":"ContextPatchingException thrown by Espresso's pre-initialization support when the Java version requested for a new context differs from the Java version the pre-initialized language image was built with. Pre-initialized Espresso (e.g. in a native image or preinit mode) can only serve contexts whose --java-version matches its own class-library version. The message reports the expected (language) version and the received (context) version.","triggerScenarios":"Creating a context with espresso.JavaVersion / --java-version=N (or a Context builder option) that differs from the version baked into the pre-initialized language; using a preinit-enabled Espresso deployment and switching the runtime java.version property or the config option between image build and context creation.","commonSituations":"Native-image builds of polyglot apps where the image was generated with one JDK class-library version and the app later configures another (e.g. 17 vs 21); CI pipelines upgrading the guest JDK without regenerating the image; mixing a stale preinit cache after a JDK upgrade.","solutions":["Set the context's Java version option to exactly the version reported as 'expected' in the message (the pre-initialized language's version).","If a different Java version is required, rebuild the pre-initialized image / clear the preinit cache with that version so language and context agree.","Check for stray java.version system properties or config files overriding the intended version at context creation."],"exampleFix":"// before\nContext ctx = Context.newBuilder(\"java\")\n    .option(\"java.JavaVersion\", \"21\")  // image preinit was built with 17\n    .build();\n// after\nContext ctx = Context.newBuilder(\"java\")\n    .option(\"java.JavaVersion\", \"17\")  // match the pre-initialized language version\n    .build();","handlingStrategy":"validation","validationCode":"// before building the context, compare requested version with the preinit language version\nString expected = System.getProperty(\"espresso.preinit.javaversion\", \"17\");\nif (!requestedJavaVersion.equals(expected)) {\n    throw new IllegalStateException(\"Pre-initialized Espresso is \" + expected + \"; refusing to create context for \" + requestedJavaVersion);\n}","typeGuard":null,"tryCatchPattern":"catch (ContextPatchingException e) { // if the factory method exposes it\n    // log and fall back to a non-preinitialized context or rebuild image\n}","preventionTips":["Record the guest Java version used at image build time and assert on it at startup.","Regenerate preinit images whenever the JDK is upgraded.","Avoid overriding java.version via properties in polyglot apps."],"tags":["espresso","preinit","java-version","native-image","configuration"],"backgroundTag":null,"analyzedSha":"a66e9ccd1d7bf2552883939aa0788dfd0e294aab","analyzedAt":"2026-08-14T13:58:47.161Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}