pinpoint-apm/pinpoint · error · InstrumentException

invalid class hierarchy. source class=${sourceClassInternalN

Error message

invalid class hierarchy. source class=${sourceClassInternalName}, advice class=${adviceClassInternalName}, super class=${superClassInternalName}

What it means

After checking the @Aspect annotation, weaving() validates the class hierarchy: the advice class must be a subclass of the source class, or its superclass must be java/lang/Object. Otherwise the weaved code would be invalid, so InstrumentException is thrown with source, advice, and superclass internal names.

Source

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

    public void weaving(final ASMClassNodeAdapter sourceClassNode, final ASMClassNodeAdapter adviceClassNode) throws InstrumentException {
        if (sourceClassNode == null || adviceClassNode == null) {
            throw new InstrumentException("source and advice class node must not be null.");
        }

        if (logger.isInfoEnabled()) {
            logger.info("weaving sourceClass={} adviceClass={}", sourceClassNode.getInternalName(), adviceClassNode.getInternalName());
        }

        if (!adviceClassNode.hasAnnotation(Aspect.class)) {
            throw new InstrumentException("@Aspect not found. adviceClass=" + adviceClassNode.getInternalName());
        }

        // advice class hierarchy check.
        final boolean isSubclass = adviceClassNode.subclassOf(sourceClassNode.getInternalName());
        if (!isSubclass) {
            final String superClassInternalName = adviceClassNode.getSuperClassInternalName();
            if (superClassInternalName == null || !superClassInternalName.equals("java/lang/Object")) {
                throw new InstrumentException("invalid class hierarchy. source class=" + sourceClassNode.getInternalName() + ", advice class=" + adviceClassNode.getInternalName() + ", super class=" + superClassInternalName);
            }
        }

        // find annotation methods and copy utility methods.
        final MethodNodes methodNodes = findMethodNodes(adviceClassNode);

        copyUtilMethods(methodNodes, sourceClassNode);
        copyPointCutMethods(methodNodes, sourceClassNode);
    }

    private MethodNodes findMethodNodes(final ASMClassNodeAdapter adviceClassNode) {
        final MethodNodes methodNodes = new MethodNodes();
        for (ASMMethodNodeAdapter methodNode : adviceClassNode.getDeclaredMethods()) {
            if (methodNode.hasAnnotation(PointCut.class)) {
                methodNodes.pointCuts.add(methodNode);
                continue;
            }
            if (methodNode.hasAnnotation(JointPoint.class)) {

View on GitHub (pinned to 744c3d3075)

Solutions

1. Make the advice class extend the source class (or java/lang/Object)
2. Ensure you pass source and advice class nodes in the correct order to weaving()
3. Regenerate the advice class after a target class hierarchy change
4. Verify superclass internal names match the expected hierarchy

Example fix

// before
public class MyAdvice extends SomeOtherBase { ... }
// after
public class MyAdvice extends TargetClass { ... }

boolean ok = adviceClassNode.subclassOf(sourceClassNode.getInternalName()) || "java/lang/Object".equals(adviceClassNode.getSuperClassInternalName());

try { weaver.weaving(src, adv); } catch (InstrumentException e) { logger.error("hierarchy invalid: {}", e.getMessage()); }

When it happens

Trigger: Weaving when adviceClassNode is neither a subclass of the source class nor a direct child of Object — e.g. advice extends a different base class than the target.

Common situations: Advice class written against an older version of the target class; the target's hierarchy changed and the advice no longer extends it; or source/advice class pair mixed up in the call.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• source and advice class node must not be null.
• @Aspect not found. adviceClass=${adviceClassInternalName}
• not found new method. ${classInternalName}.${methodName}
• non private UtilMethod unsupported. method=${methodLongName}
• not found method. ${classInternalName}.${methodName}

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