oracle/graal · error · IllegalStateException

Class not found for polyglot type conversion handler: {}

Error message

Class not found for polyglot type conversion handler: {}

What it means

IllegalStateException from PolyglotTypeMappings' converter loop: each type-converter entry maps a guest type name to a conversion handler class; if loadKlassOrNull cannot load the handler class via the bindings loader (missing from the guest classpath, misspelled, or in a jar not visible to that loader), startup fails with 'Class not found for polyglot type conversion handler: <fqn>'.

Source

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

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

View on GitHub (pinned to a66e9ccd1d)

Solutions

Add the jar (or directory) containing the handler class to the Espresso guest classpath option.
Double-check the fully-qualified name in the option string against the actual class.
Rebuild the shaded jar ensuring handler classes are preserved (no minimizing/renaming).
Verify the handler also implements GuestTypeConversion and exposes the Object(Object) method, which is checked right after this load.

Example fix

# before: handler class not on guest classpath
Context.newBuilder("java")
    .option("espresso.PolyglotTypeConverters", "my.Type:com.acme.convert.MyConverter")
    .build();  # throws

# after
Context.newBuilder("java")
    .option("espresso.javahomeclasspath", "/app/libs/converters.jar")
    .option("espresso.PolyglotTypeConverters", "my.Type:com.acme.convert.MyConverter")
    .build();

Defensive patterns

Strategy: validation

Validate before calling

Class<?> handler = Class.forName(conversionHandlerFqn, false, bindingsLoaderProxy);
if (handler == null) throw new IllegalStateException("handler not on guest classpath: " + conversionHandlerFqn);

Try / catch

try {
    Context.newBuilder("java").option("espresso.PolyglotTypeConverters", converters).build();
} catch (IllegalStateException e) {
    // handler class named in message: add its jar to classpath or fix the FQN
}

Prevention

Put converter handler jars on the Espresso guest classpath.
Reference handler classes by their constant FQN, verified at compile time where possible.
Ensure shading/minimization steps keep handler classes intact.

When it happens

Trigger: Setting the type-converters option with a handler class name that is absent from the Espresso guest classpath; the handler jar was not added via the classpath option; typo or package rename in the handler FQN.

Common situations: Custom conversion handlers living in application jars that were not passed to the java context's classpath; moving handlers to a different package during refactoring without updating the option; shading/uber-jar builds renaming or dropping handler classes.

Related errors

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