pinpoint-apm/pinpoint · error · PinpointException

${interfaceName} not found

Error message

${interfaceName} not found

What it means

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.

Source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/PlainClassLoaderHandler.java:281

            logger.debug("className:{} super:{}", currentClass.getClassName(), superName);
        }
        // null case : package-info, module-info
        if (superName != null && !"java.lang.Object".equals(superName)) {
            if (!isSkipClass(superName, classLoader, classLoadingChecker)) {
                SimpleClassMetadata superClassBinary = classMetaMap.get(superName);
                if (isDebug) {
                    logger.debug("superClass dependency define super:{} ori:{}", superClassBinary.getClassName(), currentClass.getClassName());
                }
                define0(classLoader, attachment, superClassBinary, classMetaMap, classLoadingChecker);
            }
        }

        final List<String> interfaceList = currentClass.getInterfaceNames();
        for (String interfaceName : interfaceList) {
            if (!isSkipClass(interfaceName, classLoader, classLoadingChecker)) {
                SimpleClassMetadata interfaceClassBinary = classMetaMap.get(interfaceName);
                if (interfaceClassBinary == null) {
                    throw new PinpointException(interfaceName + " not found");
                }
                if (isDebug) {
                    logger.debug("interface dependency define interface:{} ori:{}", interfaceClassBinary.getClassName(), interfaceClassBinary.getClassName());
                }
                define0(classLoader, attachment, interfaceClassBinary, classMetaMap, classLoadingChecker);
            }
        }

        final Class<?> clazz = defineClass(classLoader, currentClass);
        attachment.putClass(currentClass.getClassName(), clazz);
    }

    private Class<?> defineClass(ClassLoader classLoader, SimpleClassMetadata classMetadata) {

        if (isDebug) {
            logger.debug("define class:{} cl:{}", classMetadata.getClassName(), classLoader);
        }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Inspect the plugin jar for the missing interface: `jar tf plugin.jar | grep <InterfaceName>`; rebuild the plugin so the interface class is included.
2. Align plugin jar and agent versions — rebuild/upgrade so the plugin jar and shipped instrumentation come from the same release.
3. Check maven-shade/assembly excludes and packaging config so classes in the plugin package (and their interfaces) are not filtered out.
4. 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.
5. Enable debug logging for the profiler to see the define0 traversal and confirm which jar entries were parsed.

Example fix

// before: plugin.jar built with interface excluded
<excludes><exclude>com/myplugin/api/TracePluginInterface.class</exclude></excludes>
// after: keep the interface in the shaded plugin jar
<excludes/><!-- interface stays packaged with the plugin classes -->

// verify the interface is packaged before deployment
jar tf my-plugin.jar | grep 'com/myplugin/api/TracePluginInterface.class' || echo 'MISSING interface - rebuild plugin'

try {
    injector.injectClass(cl, pluginClassName);
} catch (PinpointException e) {
    if (e.getMessage().endsWith(" not found")) {
        logger.error("plugin jar missing interface {}: check plugin packaging/versions", e.getMessage().replace(" not found", ""));
    } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to load plugin class ${className} with classLoader ${
• not found Caused by:
• ${pluginConfig.getPluginJarURLExternalForm()} read fail.${ex
• J9BootLoader create fail Caused by:
• initialize fail Caused by:

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/043f6a125f9e1a20. Report an issue: GitHub.