pinpoint-apm/pinpoint · error · InstrumentException

${interceptorClassName} not found Caused by:${ex.getMessage(

Error message

${interceptorClassName} not found Caused by:${ex.getMessage()}

What it means

loadInterceptorClass loads an interceptor class into the target classloader via pluginContext.injectClass and wraps any failure into an InstrumentException stating '<interceptorClassName> not found'. This usually means the interceptor class is not visible to the target application's classloader, not that it is absent from the agent jar.

Source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/ASMClass.java:382

                    logger.debug("Skip addSetter, setter already declared. class={}, setter={}", getName(), setterClass.getName());
                }
            } catch (Exception e) {
                if (finalRemoved) {
                    fieldNode.setAccess(original);
                }
                throw e;
            }
        } catch (Exception e) {
            throw new InstrumentException("Failed to add setter: " + setterClass.getName(), e);
        }
    }

    private Class<? extends Interceptor> loadInterceptorClass(String interceptorClassName) throws InstrumentException {
        try {
            final ClassLoader classLoader = classNode.getClassLoader();
            return this.pluginContext.injectClass(classLoader, interceptorClassName);
        } catch (Exception ex) {
            throw new InstrumentException(interceptorClassName + " not found Caused by:" + ex.getMessage(), ex);
        }
    }


    private int addInterceptor0(Class<? extends Interceptor> interceptorClass, Object[] constructorArgs, InterceptorScope scope, ExecutionPolicy executionPolicy) throws InstrumentException {
        int interceptorId = -1;

        final TargetMethods targetMethods = interceptorClass.getAnnotation(TargetMethods.class);
        if (targetMethods != null) {
            for (TargetMethod m : targetMethods.value()) {
                interceptorId = addInterceptor0(m, interceptorClass, constructorArgs, scope, executionPolicy);
            }
        }

        final TargetMethod targetMethod = interceptorClass.getAnnotation(TargetMethod.class);
        if (targetMethod != null) {
            interceptorId = addInterceptor0(targetMethod, interceptorClass, constructorArgs, scope, executionPolicy);
        }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Ensure the interceptor class is packaged in the plugin jar deployed to the agent's plugin directory
2. Check the interceptor class name for typos and correct package
3. Inspect the cause message: if ClassNotFoundException, fix packaging/classloader visibility; if linkage errors, fix dependencies
4. Verify the target classloader can see plugin classes (use Pinpoint's classloader rules or move the class to a visible location)

Example fix

// before
clazz.addScopedInterceptor("com.example.Mynterceptor", SCOPE); // typo
// after
clazz.addScopedInterceptor("com.example.MyInterceptor", SCOPE);

try {
    Class.forName(interceptorClassName, false, pluginClassLoader);
} catch (ClassNotFoundException e) { /* fix packaging before deploying */ }

try {
    clazz.addInterceptor(interceptorClassName);
} catch (InstrumentException e) {
    logger.warn("interceptor {} not loadable: {}", interceptorClassName, e.getMessage());
}

When it happens

Trigger: addInterceptor/addScopedInterceptor is called with an interceptor class name that injectClass cannot load into classNode.getClassLoader(); any Exception from injectClass is converted to this message.

Common situations: Interceptor class not packaged in the plugin jar; classloader visibility issues (bootstrap vs app classloader); typo in the interceptor class name; plugin not deployed in the agent's plugin directory.

Related errors

• annotationKey name must not be empty
• matcher type must not be empty
• Unknown matcher type :
• not found interceptorHolderClass, className=
• not found interceptor, className=

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