{"record":{"id":"043f6a125f9e1a20","repo":"pinpoint-apm/pinpoint","slug":"interfacename-not-found","errorCode":null,"errorMessage":"${interfaceName} not found","messagePattern":"(.+?) not found","errorType":"exception","errorClass":"PinpointException","httpStatus":null,"severity":"error","filePath":"agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/PlainClassLoaderHandler.java","lineNumber":281,"sourceCode":"            logger.debug(\"className:{} super:{}\", currentClass.getClassName(), superName);\n        }\n        // null case : package-info, module-info\n        if (superName != null && !\"java.lang.Object\".equals(superName)) {\n            if (!isSkipClass(superName, classLoader, classLoadingChecker)) {\n                SimpleClassMetadata superClassBinary = classMetaMap.get(superName);\n                if (isDebug) {\n                    logger.debug(\"superClass dependency define super:{} ori:{}\", superClassBinary.getClassName(), currentClass.getClassName());\n                }\n                define0(classLoader, attachment, superClassBinary, classMetaMap, classLoadingChecker);\n            }\n        }\n\n        final List<String> interfaceList = currentClass.getInterfaceNames();\n        for (String interfaceName : interfaceList) {\n            if (!isSkipClass(interfaceName, classLoader, classLoadingChecker)) {\n                SimpleClassMetadata interfaceClassBinary = classMetaMap.get(interfaceName);\n                if (interfaceClassBinary == null) {\n                    throw new PinpointException(interfaceName + \" not found\");\n                }\n                if (isDebug) {\n                    logger.debug(\"interface dependency define interface:{} ori:{}\", interfaceClassBinary.getClassName(), interfaceClassBinary.getClassName());\n                }\n                define0(classLoader, attachment, interfaceClassBinary, classMetaMap, classLoadingChecker);\n            }\n        }\n\n        final Class<?> clazz = defineClass(classLoader, currentClass);\n        attachment.putClass(currentClass.getClassName(), clazz);\n    }\n\n    private Class<?> defineClass(ClassLoader classLoader, SimpleClassMetadata classMetadata) {\n\n        if (isDebug) {\n            logger.debug(\"define class:{} cl:{}\", classMetadata.getClassName(), classLoader);\n        }\n","sourceCodeStart":263,"sourceCodeEnd":299,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/PlainClassLoaderHandler.java#L263-L299","documentation":"When defining a plugin class into a target classloader, PlainClassLoaderHandler.define0() recursively defines the class's dependencies that live inside the plugin jar. If a class declares an interface whose name passes the plugin package filter (so it must be defined from the jar), but its metadata is absent from the parsed plugin jar map, this PinpointException is thrown. It signals an incomplete plugin jar: an interface required by a plugin class is neither loadable by the target classloader nor packaged in the jar.","triggerScenarios":"injectClass() on a plugin class whose class metadata map (parsed from the plugin jar) lacks the interface name: the interface's package matches the plugin package filter but its .class file is missing from the jar, the interface was excluded by the packaging/build config, or the plugin was compiled against a newer/renamed interface than what was packaged.","commonSituations":"Shading a plugin jar with exclusions that drop interface classes; mixing plugin jar and agent versions built from different commits; multi-module plugin where the api module jar was not copied into the plugin directory; package rename/refactor where instrumentation still references the old interface name.","solutions":["Inspect the plugin jar for the missing interface: `jar tf plugin.jar | grep <InterfaceName>`; rebuild the plugin so the interface class is included.","Align plugin jar and agent versions — rebuild/upgrade so the plugin jar and shipped instrumentation come from the same release.","Check maven-shade/assembly excludes and packaging config so classes in the plugin package (and their interfaces) are not filtered out.","If the interface is supposed to come from the app classloader instead, adjust the plugin package filter so the interface is skipped (isSkipClass) rather than required from the jar.","Enable debug logging for the profiler to see the define0 traversal and confirm which jar entries were parsed."],"exampleFix":"// before: plugin.jar built with interface excluded\n<excludes><exclude>com/myplugin/api/TracePluginInterface.class</exclude></excludes>\n// after: keep the interface in the shaded plugin jar\n<excludes/><!-- interface stays packaged with the plugin classes -->","handlingStrategy":"validation","validationCode":"// verify the interface is packaged before deployment\njar tf my-plugin.jar | grep 'com/myplugin/api/TracePluginInterface.class' || echo 'MISSING interface - rebuild plugin'","typeGuard":null,"tryCatchPattern":"try {\n    injector.injectClass(cl, pluginClassName);\n} catch (PinpointException e) {\n    if (e.getMessage().endsWith(\" not found\")) {\n        logger.error(\"plugin jar missing interface {}: check plugin packaging/versions\", e.getMessage().replace(\" not found\", \"\"));\n    } else throw e;\n}","preventionTips":["Package plugin api interfaces together with the plugin classes (same shaded jar, no excludes).","Keep plugin jar and agent versions in lockstep; never mix plugin jars from different releases.","Run a CI check that every interface referenced by plugin classes resolves inside the jar.","After any package rename, rebuild and re-test plugin loading in a staging agent before production."],"tags":["java","pinpoint-agent","plugin-loading","class-not-found","classloader"],"backgroundTag":"class-not-found","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}