oracle/graal · critical · IllegalStateException

Espresso VMAccess cannot be built because the Polyglot engin

Error message

Espresso VMAccess cannot be built because the Polyglot engine does not expose the 'java' language. Check that the Espresso language is installed and visible on the module path.

What it means

IllegalStateException thrown by EspressoExternalVMAccessBuilder.ensureJavaLanguageAvailable(): before processing java.* options, the builder starts a temporary Polyglot Engine and checks that a language with id 'java' (Espresso) is registered. If Espresso is not on the class/module path, this fails fast with a clear message instead of a confusing unrecognized-option error later.

Source

Thrown at espresso-compiler-stub/src/com.oracle.truffle.espresso.vmaccess/src/com/oracle/truffle/espresso/vmaccess/EspressoExternalVMAccessBuilder.java:258

                } else if (engine.getInstruments().containsKey(group)) {
                    descriptors = engine.getInstruments().get(group).getOptions();
                }
                break;
        }
        if (descriptors == null) {
            return null;
        }
        return descriptors.get(key);
    }

    /**
     * Fail before processing {@code java.*} options when Espresso is not available to the temporary
     * engine. Otherwise missing Espresso dependencies surface later as a generic
     * unrecognized-option error for the first {@code java.*} option.
     */
    private static void ensureJavaLanguageAvailable() {
        if (!getTempEngine().getLanguages().containsKey(JAVA_LANGUAGE_ID)) {
            throw new IllegalStateException("Espresso VMAccess cannot be built because the Polyglot engine does not expose the '" + JAVA_LANGUAGE_ID +
                            "' language. Check that the Espresso language is installed and visible on the module path.");
        }
    }

    private static Engine getTempEngine() {
        if (tempEngine == null) {
            tempEngine = Engine.newBuilder().useSystemProperties(false).//
                            out(OutputStream.nullOutputStream()).//
                            err(OutputStream.nullOutputStream()).//
                            option("engine.WarnInterpreterOnly", "false").//
                            build();
        }
        return tempEngine;
    }

    private static final class ModuleAccess {
        static {
            ModuleSupport.addExports("jdk.internal.vm.ci.espresso", "jdk.internal.vm.ci",

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Add the Espresso implementation dependency (com.oracle.truffle:truffle-espresso / truffle language jar) to the runtime classpath or module path
2. If shading, merge META-INF/services resource files (e.g. maven-shade ServicesResourceTransformer) so the TruffleLanguage registration survives
3. Check for GraalVM version alignment: the SDK in truffle-api and the Espresso build must come from the same release

Example fix

// before (gradle): espresso marked provided -> language missing at runtime
// after
dependencies { implementation "org.graalvm.polyglot:espresso-community:<same-version-as-polyglot>" }

// pre-flight check
if (!Engine.newBuilder().build().getLanguages().containsKey("java")) {
    throw new IllegalStateException("Espresso language not on classpath");
}

try (Engine probe = Engine.newBuilder().useSystemProperties(false).build()) {
    if (!probe.getLanguages().containsKey("java")) {
        throw new IllegalStateException("Espresso language missing from classpath/module path");
    }
}

catch (IllegalStateException e) { instruct: add the Espresso runtime dependency / fix shading; list detected languages }

When it happens

Trigger: Building EspressoExternalVMAccess when the truffle-espresso language jar (with its language registration) is not on the application's classpath/module path, or when a custom Truffle language setup excludes it; also when a shading/relocation stripped the META-INF/services language registration.

Common situations: Maven/Gradle dependency marked 'provided' or pruned by the resolver; fat-jar shading dropping META-INF/services/com.oracle.truffle.api.TruffleLanguage; running on a JDK without the GraalVM module layout; mixing incompatible GraalVM SDK and Espresso versions so the language never registers.

Related errors

• Missing expected guest type conversion interface in polyglot
• Class not found for polyglot type conversion handler: {}
• No %s providers found
• Espresso cannot evaluate Java sources directly, only a few s
• invalid interface type mapping specified: {}

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