oracle/graal · error · IllegalStateException

invalid interface type mapping specified: {}

Error message

invalid interface type mapping specified: {}

What it means

IllegalStateException from PolyglotTypeMappings while resolving the Context option 'espresso.PolyglotInterfaceMappings' (polyglot.java.Jasmine-style interface mappings): each mapping string must resolve, via the bindings loader, to an existing class that is actually an interface. If loadKlassOrNull returns null (class missing) or the loaded Klass is not an interface, configuration aborts with 'invalid interface type mapping specified: <mapping>'.

Source

Thrown at espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/nodes/interop/PolyglotTypeMappings.java:98

        this.builtinCollections = builtinCollections;
    }

    @TruffleBoundary
    public void resolve(EspressoContext context) {
        assert interfaceMappings != null;

        // resolve interface mappings
        if (hasInterfaceMappings) {
            EconomicMap<String, ObjectKlass> temp = EconomicMap.create(interfaceMappings.size());
            StaticObject bindingsLoader = context.getBindingsLoader();

            for (String mapping : interfaceMappings) {
                Klass parent = context.getMeta().loadKlassOrNull(context.getTypes().fromClassGetName(mapping), bindingsLoader, StaticObject.NULL);
                if (parent != null && parent.isInterface()) {
                    temp.put(mapping, (ObjectKlass) parent);
                    parent.typeConversionState = Klass.INTERFACE_MAPPED;
                } else {
                    throw new IllegalStateException("invalid interface type mapping specified: " + mapping);
                }
            }
            mappedInterfaces = EconomicMap.create(temp);
        }
        // resolve type converters
        Set<Map.Entry<String, String>> converters = typeConverters.entrySet();
        if (!converters.isEmpty()) {
            EconomicMap<String, TypeConverter> temp = EconomicMap.create(converters.size());
            StaticObject bindingsLoader = context.getBindingsLoader();

            Symbol<Name> name = Names.toGuest;
            Symbol<Signature> desc = Signatures.Object_Object;

            // load the GuestTypeConversion interface for type checking
            Klass conversionInterface = context.getMeta().loadKlassOrNull(context.getTypes().fromClassGetName(GUEST_TYPE_CONVERSION_INTERFACE), bindingsLoader, StaticObject.NULL);
            if (conversionInterface == null) {
                throw new IllegalStateException("Missing expected guest type conversion interface in polyglot.jar");
            }

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Verify each mapping string is the correct fully-qualified interface name and that the interface exists on the guest classpath.
2. Change the target to an actual interface (type mappings require interfaces, not classes).
3. Add the containing jar/directory to the Espresso classpath option before resolution.
4. Remove stale mappings left over from refactors.

Example fix

# before
Context ctx = Context.newBuilder("java")
    .option("espresso.PolyglotInterfaceMappings", "com.acme.ShapeImpl")  # a class!
    .build();

# after
Context ctx = Context.newBuilder("java")
    .option("espresso.PolyglotInterfaceMappings", "com.acme.Shape")  # the interface
    .build();

Class<?> c = Class.forName(mapping, false, bindingsLoaderProxy);
if (!c.isInterface()) {
    throw new IllegalArgumentException(mapping + " is not an interface");
}

try {
    Context.newBuilder("java").option("espresso.PolyglotInterfaceMappings", mappings).build();
} catch (IllegalStateException e) {
    // invalid mapping named in message: fix spelling/target or add its jar to classpath
}

When it happens

Trigger: Setting the interface-mappings option with a fully-qualified type name that does not exist on the guest classpath, is a class (not interface), or is misspelled; mappings are resolved eagerly at context startup, so any bad entry kills context creation.

Common situations: Typos in host language option values; mapping to a class instead of an interface; the interface living in a jar not on the Espresso classpath; renaming the interface between versions without updating the option string.

Related errors

• Class not found for polyglot type conversion handler: {}
• Missing expected guest type conversion interface in polyglot
• ConversionHandler does not implement the polyglot type conve
• JImage=native can only be set if native access is allowed
• Espresso cannot evaluate Java sources directly, only a few s

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