oracle/graal · error · ContextPatchingException

Configuration specified a Java version incompatible with the

Error message

Configuration specified a Java version incompatible with the pre-initialized language - expected: %s, got: %s.

What it means

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.

Source

Thrown at espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/preinit/ContextPatchingException.java:36

 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
package com.oracle.truffle.espresso.preinit;

import com.oracle.truffle.api.CompilerAsserts;
import com.oracle.truffle.espresso.classfile.JavaVersion;

public final class ContextPatchingException extends Exception {

    private static final long serialVersionUID = -762795124477419520L;

    public static ContextPatchingException javaVersionMismatch(JavaVersion languageJavaVersion, JavaVersion contextJavaVersion) throws ContextPatchingException {
        CompilerAsserts.neverPartOfCompilation();
        String errMsg = String.format("Configuration specified a Java version incompatible with the pre-initialized language - expected: %s, got: %s.", languageJavaVersion,
                        contextJavaVersion);
        throw new ContextPatchingException(errMsg);
    }

    private ContextPatchingException(String message) {
        super(message);
    }
}

View on GitHub (pinned to a66e9ccd1d)

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.

Example fix

// before
Context ctx = Context.newBuilder("java")
    .option("java.JavaVersion", "21")  // image preinit was built with 17
    .build();
// after
Context ctx = Context.newBuilder("java")
    .option("java.JavaVersion", "17")  // match the pre-initialized language version
    .build();

Defensive patterns

Strategy: validation

Validate before calling

// before building the context, compare requested version with the preinit language version
String expected = System.getProperty("espresso.preinit.javaversion", "17");
if (!requestedJavaVersion.equals(expected)) {
    throw new IllegalStateException("Pre-initialized Espresso is " + expected + "; refusing to create context for " + requestedJavaVersion);
}

Try / catch

catch (ContextPatchingException e) { // if the factory method exposes it
    // log and fall back to a non-preinitialized context or rebuild image
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of oracle/graal@a66e9ccd1d (2026-08-14). Data as JSON: /api/errors/a10c6ca7f5dea429. Report an issue: GitHub.