{"record":{"id":"848ca7a790b23eb3","repo":"oracle/graal","slug":"invalid-interface-type-mapping-specified","errorCode":null,"errorMessage":"invalid interface type mapping specified: {}","messagePattern":"invalid interface type mapping specified: (.+?)","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":98,"sourceCode":"        this.builtinCollections = builtinCollections;\n    }\n\n    @TruffleBoundary\n    public void resolve(EspressoContext context) {\n        assert interfaceMappings != null;\n\n        // resolve interface mappings\n        if (hasInterfaceMappings) {\n            EconomicMap<String, ObjectKlass> temp = EconomicMap.create(interfaceMappings.size());\n            StaticObject bindingsLoader = context.getBindingsLoader();\n\n            for (String mapping : interfaceMappings) {\n                Klass parent = context.getMeta().loadKlassOrNull(context.getTypes().fromClassGetName(mapping), bindingsLoader, StaticObject.NULL);\n                if (parent != null && parent.isInterface()) {\n                    temp.put(mapping, (ObjectKlass) parent);\n                    parent.typeConversionState = Klass.INTERFACE_MAPPED;\n                } 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            }","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/oracle/graal/blob/a66e9ccd1d7bf2552883939aa0788dfd0e294aab/espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/nodes/interop/PolyglotTypeMappings.java#L80-L116","documentation":"IllegalStateException from PolyglotTypeMappings while resolving the Context option 'espresso.PolyglotInterfaceMappings' (polyglot.java.Jasmine-style interface mappings): each mapping string must resolve, via the bindings loader, to an existing class that is actually an interface. If loadKlassOrNull returns null (class missing) or the loaded Klass is not an interface, configuration aborts with 'invalid interface type mapping specified: <mapping>'.","triggerScenarios":"Setting the interface-mappings option with a fully-qualified type name that does not exist on the guest classpath, is a class (not interface), or is misspelled; mappings are resolved eagerly at context startup, so any bad entry kills context creation.","commonSituations":"Typos in host language option values; mapping to a class instead of an interface; the interface living in a jar not on the Espresso classpath; renaming the interface between versions without updating the option string.","solutions":["Verify each mapping string is the correct fully-qualified interface name and that the interface exists on the guest classpath.","Change the target to an actual interface (type mappings require interfaces, not classes).","Add the containing jar/directory to the Espresso classpath option before resolution.","Remove stale mappings left over from refactors."],"exampleFix":"# before\nContext ctx = Context.newBuilder(\"java\")\n    .option(\"espresso.PolyglotInterfaceMappings\", \"com.acme.ShapeImpl\")  # a class!\n    .build();\n\n# after\nContext ctx = Context.newBuilder(\"java\")\n    .option(\"espresso.PolyglotInterfaceMappings\", \"com.acme.Shape\")  # the interface\n    .build();","handlingStrategy":"validation","validationCode":"Class<?> c = Class.forName(mapping, false, bindingsLoaderProxy);\nif (!c.isInterface()) {\n    throw new IllegalArgumentException(mapping + \" is not an interface\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    Context.newBuilder(\"java\").option(\"espresso.PolyglotInterfaceMappings\", mappings).build();\n} catch (IllegalStateException e) {\n    // invalid mapping named in message: fix spelling/target or add its jar to classpath\n}","preventionTips":["Only map to real interfaces present on the guest classpath.","Derive mapping strings from constants, not hand-typed strings, to avoid typos.","Test context creation in CI to catch bad mappings early."],"tags":["polyglot","configuration","type-mapping","espresso"],"backgroundTag":null,"analyzedSha":"a66e9ccd1d7bf2552883939aa0788dfd0e294aab","analyzedAt":"2026-08-14T13:58:47.161Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}