oracle/graal · error · IllegalStateException

ConversionHandler does not implement the polyglot type conve

Error message

ConversionHandler does not implement the polyglot type conversion interface: com.oracle.truffle.espresso.polyglot.GuestTypeConversion

What it means

Espresso throws this IllegalStateException while initializing polyglot type converters (PolyglotTypeMappings) when a class configured as a conversion handler cannot be assigned to the guest interface com.oracle.truffle.espresso.polyglot.GuestTypeConversion. The handler class is resolved by name from the converters configuration, loaded through the guest class loader, and then checked with conversionInterface.isAssignableFrom. A failure means the configured class exists but is not a valid converter implementation.

Source

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

            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())));
            }
            typeConverterFunctions = EconomicMap.create(temp);
        }
        addInternalConverters(context.getMeta());
        if (builtinCollections) {
            EconomicMap<String, ObjectKlass> temp = EconomicMap.create(6);
            addInternalEspressoCollections(temp, context.getMeta());
            espressoForeignCollections = EconomicMap.create(temp);
        }
    }

    private void addInternalConverters(Meta meta) {
        EconomicMap<String, InternalTypeConverter> converters = EconomicMap.create(2);

View on GitHub (pinned to a66e9ccd1d)

Solutions

Make the configured handler class implement com.oracle.truffle.espresso.polyglot.GuestTypeConversion (implement all its methods) and rebuild.
Verify the fully-qualified class name in the converter configuration matches the actual handler class and that the class is visible to the bindings class loader.
Recompile the handler against the exact GraalVM/Espresso version in use so the interface signature matches.
If the handler was intentionally removed, delete its entry from the converters configuration instead of leaving a stale mapping.

Example fix

// before
public final class MyConverter {  // does not implement the guest interface
    public Object convert(Object v) { return v; }
}
// after
public final class MyConverter implements com.oracle.truffle.espresso.polyglot.GuestTypeConversion {
    // implement every method of GuestTypeConversion
}
// and ensure the option maps: "my.Type" -> "com.example.MyConverter"

Defensive patterns

Strategy: validation

Validate before calling

// before creating the context, check the handler class on the host side
Class<?> iface = Class.forName("com.oracle.truffle.espresso.polyglot.GuestTypeConversion");
Class<?> handler = Class.forName(configuredHandlerName);
if (!iface.isAssignableFrom(handler)) {
    throw new ConfigurationError(configuredHandlerName + " must implement " + iface.getName());
}

Prevention

Keep converter handler implementations in the same build/dependency graph as the GraalVM version being targeted.
Add a startup self-test that loads and assignability-checks every configured converter handler.
Treat converter config as code: version it and re-run the check whenever GraalVM is upgraded.

When it happens

Trigger: Setting the Espresso polyglot type-converter option (a map of type name -> handler class name, e.g. via Context builder or espresso polyglot type converter configuration) where the handler class does not implement com.oracle.truffle.espresso.polyglot.GuestTypeConversion; also pointing the config at a class that only implements an older/incompatible version of the interface, or at an interface/abstract class instead of a concrete implementation.

Common situations: Upgrading GraalVM/Espresso where GuestTypeConversion gained methods and an old handler no longer satisfies it; typos or stale fully-qualified class names in the converter configuration; using a handler compiled against a different Espresso version; placing the handler on the wrong classpath so a same-named but wrong class is loaded.

Related errors

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