{"record":{"id":"57edcad1bcd6b9c9","repo":"oracle/graal","slug":"class-not-found-for-polyglot-type-conversion-handl","errorCode":null,"errorMessage":"Class not found for polyglot type conversion handler: {}","messagePattern":"Class not found for polyglot type conversion handler: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/nodes/interop/PolyglotTypeMappings.java","lineNumber":124,"sourceCode":"            EconomicMap<String, TypeConverter> temp = EconomicMap.create(converters.size());\n            StaticObject bindingsLoader = context.getBindingsLoader();\n\n            Symbol<Name> name = Names.toGuest;\n            Symbol<Signature> desc = Signatures.Object_Object;\n\n            // load the GuestTypeConversion interface for type checking\n            Klass conversionInterface = context.getMeta().loadKlassOrNull(context.getTypes().fromClassGetName(GUEST_TYPE_CONVERSION_INTERFACE), bindingsLoader, StaticObject.NULL);\n            if (conversionInterface == null) {\n                throw new IllegalStateException(\"Missing expected guest type conversion interface in polyglot.jar\");\n            }\n\n            for (Map.Entry<String, String> entry : converters) {\n                String type = entry.getKey();\n\n                String conversionHandler = entry.getValue();\n                ObjectKlass conversionKlass = (ObjectKlass) context.getMeta().loadKlassOrNull(context.getTypes().fromClassGetName(conversionHandler), bindingsLoader, StaticObject.NULL);\n                if (conversionKlass == null) {\n                    throw new IllegalStateException(\"Class not found for polyglot type conversion handler: \" + conversionHandler);\n                }\n                // make sure the conversion class implements GuestTypeConversion interface\n                if (!conversionInterface.isAssignableFrom(conversionKlass)) {\n                    throw new IllegalStateException(\"ConversionHandler does not implement the polyglot type conversion interface: \" + GUEST_TYPE_CONVERSION_INTERFACE);\n                }\n                Method conversionMethod = conversionKlass.requireDeclaredMethod(name, desc);\n                StaticObject conversionReceiver = context.getAllocator().createNew(conversionKlass);\n                temp.put(type, new TypeConverterImpl(conversionReceiver, DirectCallNode.create(conversionMethod.getCallTarget())));\n            }\n            typeConverterFunctions = EconomicMap.create(temp);\n        }\n        addInternalConverters(context.getMeta());\n        if (builtinCollections) {\n            EconomicMap<String, ObjectKlass> temp = EconomicMap.create(6);\n            addInternalEspressoCollections(temp, context.getMeta());\n            espressoForeignCollections = EconomicMap.create(temp);\n        }\n    }","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/oracle/graal/blob/a66e9ccd1d7bf2552883939aa0788dfd0e294aab/espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/nodes/interop/PolyglotTypeMappings.java#L106-L142","documentation":"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>'.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before: handler class not on guest classpath\nContext.newBuilder(\"java\")\n    .option(\"espresso.PolyglotTypeConverters\", \"my.Type:com.acme.convert.MyConverter\")\n    .build();  # throws\n\n# after\nContext.newBuilder(\"java\")\n    .option(\"espresso.javahomeclasspath\", \"/app/libs/converters.jar\")\n    .option(\"espresso.PolyglotTypeConverters\", \"my.Type:com.acme.convert.MyConverter\")\n    .build();","handlingStrategy":"validation","validationCode":"Class<?> handler = Class.forName(conversionHandlerFqn, false, bindingsLoaderProxy);\nif (handler == null) throw new IllegalStateException(\"handler not on guest classpath: \" + conversionHandlerFqn);","typeGuard":null,"tryCatchPattern":"try {\n    Context.newBuilder(\"java\").option(\"espresso.PolyglotTypeConverters\", converters).build();\n} catch (IllegalStateException e) {\n    // handler class named in message: add its jar to classpath or fix the FQN\n}","preventionTips":["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."],"tags":["polyglot","classpath","configuration","type-mapping","espresso"],"backgroundTag":null,"analyzedSha":"a66e9ccd1d7bf2552883939aa0788dfd0e294aab","analyzedAt":"2026-08-14T13:58:47.161Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}