oracle/graal · error · IllegalStateException

Missing expected guest type conversion interface in polyglot

Error message

Missing expected guest type conversion interface in polyglot.jar

What it means

IllegalStateException from PolyglotTypeMappings: when type converters are configured, Espresso must load the marker interface com.oracle.truffle.espresso.polyglot.GuestTypeConversion from polyglot.jar via the bindings loader to type-check converter classes. If that interface cannot be loaded (loadKlassOrNull returns null), startup fails with 'Missing expected guest type conversion interface in polyglot.jar', indicating a broken or mismatched polyglot.jar on the classpath.

Source

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

                } 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");
            }

            for (Map.Entry<String, String> entry : converters) {
                String type = entry.getKey();

                String conversionHandler = entry.getValue();
                ObjectKlass conversionKlass = (ObjectKlass) context.getMeta().loadKlassOrNull(context.getTypes().fromClassGetName(conversionHandler), bindingsLoader, StaticObject.NULL);
                if (conversionKlass == null) {
                    throw new IllegalStateException("Class not found for polyglot type conversion handler: " + conversionHandler);
                }
                // make sure the conversion class implements GuestTypeConversion interface
                if (!conversionInterface.isAssignableFrom(conversionKlass)) {
                    throw new IllegalStateException("ConversionHandler does not implement the polyglot type conversion interface: " + GUEST_TYPE_CONVERSION_INTERFACE);
                }
                Method conversionMethod = conversionKlass.requireDeclaredMethod(name, desc);
                StaticObject conversionReceiver = context.getAllocator().createNew(conversionKlass);
                temp.put(type, new TypeConverterImpl(conversionReceiver, DirectCallNode.create(conversionMethod.getCallTarget())));
            }

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Ensure a polyglot.jar matching your GraalVM/Truffle version is on the Espresso guest classpath.
2. Remove duplicate or stale polyglot jars (dependency tree dedup).
3. Align versions of truffle/espresso artifacts and polyglot.jar.
4. If converters are not needed, drop the converter option so the interface is never resolved.

Class<?> iface = Class.forName("com.oracle.truffle.espresso.polyglot.GuestTypeConversion", false, bindingsLoaderProxy);
if (iface == null) throw new IllegalStateException("polyglot.jar missing or outdated");

try {
    context = Context.newBuilder("java").option(...converters...).build();
} catch (IllegalStateException e) {
    // polyglot.jar mismatch: align versions on classpath, then rebuild context
}

When it happens

Trigger: Configuring type converters (espresso.PolyglotTypeConverters-style option) while the guest classpath's polyglot.jar is missing, outdated (pre-dating GuestTypeConversion), corrupted, or shadowed by another jar containing the same packages.

Common situations: Upgrading GraalVM/Truffle but keeping an old polyglot.jar on the classpath; custom trimmed classpaths that dropped polyglot.jar; duplicate/conflicting jars hiding the interface; SNAPSHOT version skew between espresso runtime and polyglot.jar.

Related errors

• Class not found for polyglot type conversion handler: {}
• invalid interface type mapping specified: {}
• Espresso VMAccess cannot be built because the Polyglot engin
• %s is not an enum type
• Unrecognized version

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