{"record":{"id":"0f9a7c9e6cbe38b7","repo":"pinpoint-apm/pinpoint","slug":"defineclass-fail","errorCode":null,"errorMessage":"defineClass fail","messagePattern":"defineClass fail","errorType":"exception","errorClass":"InstrumentException","httpStatus":null,"severity":"error","filePath":"agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/ASMInterceptorHolder.java","lineNumber":147,"sourceCode":"    }\n\n    public Class<?> loadClass(ClassLoader classLoader) throws InstrumentException {\n        try {\n            return Class.forName(className, false, classLoader);\n        } catch (ClassNotFoundException e) {\n            throw new InstrumentException(\"not found InterceptorHolderClass, className=\" + className);\n        }\n    }\n\n    public Class<?> defineClass(ClassLoader classLoader) throws InstrumentException {\n        try {\n            final byte[] mainClassBytes = toMainClassByteArray();\n            final Class<?> mainClass = InterceptorDefineClassHelper.defineClass(classLoader, className, mainClassBytes);\n            final byte[] innerClassByte = toInnerClassByteArray();\n            InterceptorDefineClassHelper.defineClass(classLoader, innerClassName, innerClassByte);\n            return mainClass;\n        } catch (Exception e) {\n            throw new InstrumentException(\"defineClass fail\", e);\n        }\n    }\n\n    byte[] toMainClassByteArray() throws InstrumentException {\n        try {\n            ClassNode classNode = readClass(INTERCEPTOR_HOLDER_CLASS);\n            final ClassWriter classWriter = new ClassWriter(ClassWriter.COMPUTE_FRAMES);\n            final ClassVisitor renameClassAdapter = new RenameClassAdapter(classWriter, className);\n            classNode.accept(renameClassAdapter);\n            return classWriter.toByteArray();\n        } catch (IOException e) {\n            // read fail\n            throw new InstrumentException(\"ClassReader fail, classFile=\" + INTERCEPTOR_HOLDER_CLASS, e);\n        }\n    }\n\n    byte[] toInnerClassByteArray() throws InstrumentException {\n        try {","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/ASMInterceptorHolder.java#L129-L165","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check getCause(): LinkageError/duplicate class means the holder is already defined — avoid double agent installation","Verify the profiler jar is intact and contains com/navercorp/pinpoint/profiler/instrument/interceptor/InterceptorHolder.class","Ensure only one Pinpoint agent is attached per JVM and the id generator produces unique ids","Match the agent version to your JDK (bytecode compatibility) and update if needed"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// guard against duplicate definition\ntry {\n    Class.forName(holder.getClassName(), false, classLoader);\n    throw new IllegalStateException(\"holder already defined: \" + holder.getClassName());\n} catch (ClassNotFoundException expected) { /* safe to define */ }","typeGuard":null,"tryCatchPattern":"try {\n    holder.defineClass(classLoader);\n} catch (InstrumentException e) {\n    if (e.getCause() instanceof LinkageError) {\n        logger.warn(\"holder {} already defined — duplicate agent?\", holder.getClassName());\n    } else {\n        logger.error(\"defineClass failed\", e);\n    }\n}","preventionTips":["Attach exactly one agent per JVM","Ship an intact profiler jar containing the InterceptorHolder templates","Keep unique interceptor ids via InterceptorHolderIdGenerator","Match agent build to target JDK bytecode support"],"tags":["asm","bytecode","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"}