pinpoint-apm/pinpoint · error · InstrumentException

defineClass fail

Error message

defineClass fail

What it means

defineClass generates holder class bytes with ASM (reading the InterceptorHolder template, renaming it) and calls InterceptorDefineClassHelper.defineClass. This InstrumentException wraps any Exception from that whole pipeline — template read failure, ClassWriter/ASM errors, or the JVM rejecting the defined class (LinkageError like duplicate class definition, SecurityException, or ClassFormatError).

Source

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

    }

    public Class<?> loadClass(ClassLoader classLoader) throws InstrumentException {
        try {
            return Class.forName(className, false, classLoader);
        } catch (ClassNotFoundException e) {
            throw new InstrumentException("not found InterceptorHolderClass, className=" + className);
        }
    }

    public Class<?> defineClass(ClassLoader classLoader) throws InstrumentException {
        try {
            final byte[] mainClassBytes = toMainClassByteArray();
            final Class<?> mainClass = InterceptorDefineClassHelper.defineClass(classLoader, className, mainClassBytes);
            final byte[] innerClassByte = toInnerClassByteArray();
            InterceptorDefineClassHelper.defineClass(classLoader, innerClassName, innerClassByte);
            return mainClass;
        } catch (Exception e) {
            throw new InstrumentException("defineClass fail", e);
        }
    }

    byte[] toMainClassByteArray() throws InstrumentException {
        try {
            ClassNode classNode = readClass(INTERCEPTOR_HOLDER_CLASS);
            final ClassWriter classWriter = new ClassWriter(ClassWriter.COMPUTE_FRAMES);
            final ClassVisitor renameClassAdapter = new RenameClassAdapter(classWriter, className);
            classNode.accept(renameClassAdapter);
            return classWriter.toByteArray();
        } catch (IOException e) {
            // read fail
            throw new InstrumentException("ClassReader fail, classFile=" + INTERCEPTOR_HOLDER_CLASS, e);
        }
    }

    byte[] toInnerClassByteArray() throws InstrumentException {
        try {

View on GitHub (pinned to 744c3d3075)

Solutions

1. Check getCause(): LinkageError/duplicate class means the holder is already defined — avoid double agent installation
2. Verify the profiler jar is intact and contains com/navercorp/pinpoint/profiler/instrument/interceptor/InterceptorHolder.class
3. Ensure only one Pinpoint agent is attached per JVM and the id generator produces unique ids
4. Match the agent version to your JDK (bytecode compatibility) and update if needed

// guard against duplicate definition
try {
    Class.forName(holder.getClassName(), false, classLoader);
    throw new IllegalStateException("holder already defined: " + holder.getClassName());
} catch (ClassNotFoundException expected) { /* safe to define */ }

try {
    holder.defineClass(classLoader);
} catch (InstrumentException e) {
    if (e.getCause() instanceof LinkageError) {
        logger.warn("holder {} already defined — duplicate agent?", holder.getClassName());
    } else {
        logger.error("defineClass failed", e);
    }
}

When it happens

Trigger: Calling defineClass (directly or via Builder.build()) when the holder class name already exists in the target classloader (duplicate agent installation / id collision), the InterceptorHolder template resource is missing or corrupt in the agent jar, or the generated bytecode violates JVM constraints on the target JDK.

Common situations: Two agents or duplicate profiler jars in one JVM; a corrupted/partially extracted pinpoint distribution; running an old agent build on a newer JDK that rejects the bytecode version; InterceptorHolderIdGenerator id collisions after many interceptions.

Related errors

• unexpected class ${className}
• source and advice class node must not be null.
• @Aspect not found. adviceClass=${adviceClassInternalName}
• invalid class hierarchy. source class=${sourceClassInternalN
• not found new method. ${classInternalName}.${methodName}

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