{"record":{"id":"72f64f74e6739e09","repo":"oracle/graal","slug":"missing-expected-guest-type-conversion-interface-i","errorCode":null,"errorMessage":"Missing expected guest type conversion interface in polyglot.jar","messagePattern":"Missing expected guest type conversion interface in polyglot\\.jar","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":115,"sourceCode":"                } else {\n                    throw new IllegalStateException(\"invalid interface type mapping specified: \" + mapping);\n                }\n            }\n            mappedInterfaces = EconomicMap.create(temp);\n        }\n        // resolve type converters\n        Set<Map.Entry<String, String>> converters = typeConverters.entrySet();\n        if (!converters.isEmpty()) {\n            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            }","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/oracle/graal/blob/a66e9ccd1d7bf2552883939aa0788dfd0e294aab/espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/nodes/interop/PolyglotTypeMappings.java#L97-L133","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure a polyglot.jar matching your GraalVM/Truffle version is on the Espresso guest classpath.","Remove duplicate or stale polyglot jars (dependency tree dedup).","Align versions of truffle/espresso artifacts and polyglot.jar.","If converters are not needed, drop the converter option so the interface is never resolved."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"Class<?> iface = Class.forName(\"com.oracle.truffle.espresso.polyglot.GuestTypeConversion\", false, bindingsLoaderProxy);\nif (iface == null) throw new IllegalStateException(\"polyglot.jar missing or outdated\");","typeGuard":null,"tryCatchPattern":"try {\n    context = Context.newBuilder(\"java\").option(...converters...).build();\n} catch (IllegalStateException e) {\n    // polyglot.jar mismatch: align versions on classpath, then rebuild context\n}","preventionTips":["Ship polyglot.jar at the same version as the GraalVM/Truffle runtime.","Deduplicate polyglot jars in dependency trees.","Run a context-creation smoke test after any dependency upgrade."],"tags":["polyglot","classpath","version-mismatch","type-mapping","espresso"],"backgroundTag":null,"analyzedSha":"a66e9ccd1d7bf2552883939aa0788dfd0e294aab","analyzedAt":"2026-08-14T13:58:47.161Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}