pinpoint-apm/pinpoint · error · IllegalArgumentException

unknown operand. operand=${operand}

Error message

unknown operand. operand=${operand}

What it means

DefaultTransformerMatcher.match dispatches a MatcherOperand to the matching strategy by instanceof checks (class, interface, annotation, super matcher operands). An operand of an unrecognized type falls through to the else branch and throws IllegalArgumentException 'unknown operand'.

Source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/transformer/DefaultTransformerMatcher.java:77

    public boolean match(ClassLoader classLoader, MatcherOperand operand, InternalClassMetadata classMetadata) {
        if (operand.isOperator()) {
            // operation
            return traversal(classLoader, operand, classMetadata);
        }

        if (operand instanceof ClassInternalNameMatcherOperand) {
            return matchClass((ClassInternalNameMatcherOperand) operand, classMetadata);
        } else if (operand instanceof PackageInternalNameMatcherOperand) {
            return matchPackage((PackageInternalNameMatcherOperand) operand, classMetadata);
        } else if (operand instanceof InterfaceInternalNameMatcherOperand) {
            return matchInterface(classLoader, (InterfaceInternalNameMatcherOperand) operand, classMetadata);
        } else if (operand instanceof AnnotationInternalNameMatcherOperand) {
            return matchAnnotation(classLoader, (AnnotationInternalNameMatcherOperand) operand, classMetadata);
        } else if (operand instanceof SuperClassInternalNameMatcherOperand) {
            return matchSuper(classLoader, (SuperClassInternalNameMatcherOperand) operand, classMetadata);
        } else {
            throw new IllegalArgumentException("unknown operand. operand=" + operand);
        }
    }

    boolean matchClass(final ClassInternalNameMatcherOperand operand, final InternalClassMetadata classMetadata) {
        if (classMetadata == null) {
            return false;
        }
        if (classMetadata.isInterface() || classMetadata.isAnnotation()) {
            // skip interface and annotation.
            return false;
        }
        return operand.match(classMetadata.getClassInternalName());
    }

    boolean matchPackage(final PackageInternalNameMatcherOperand operand, final InternalClassMetadata classMetadata) {
        if (classMetadata == null) {
            return false;
        }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Add an instanceof branch in match() handling the unknown operand type
2. Use a supported operand type (Class/Interface/Annotation/SuperClassInternalNameMatcherOperand)
3. Rebuild the plugin against the agent's matcher API version so operand classes align

Example fix

// before
} else {
    throw new IllegalArgumentException("unknown operand. operand=" + operand);
}
// after
} else if (operand instanceof MyCustomOperand) {
    return matchCustom(classLoader, (MyCustomOperand) operand, classMetadata);
} else {
    throw new IllegalArgumentException("unknown operand. operand=" + operand);
}

if (!(operand instanceof ClassInternalNameMatcherOperand || operand instanceof InterfaceInternalNameMatcherOperand || operand instanceof AnnotationInternalNameMatcherOperand || operand instanceof SuperClassInternalNameMatcherOperand)) throw new IllegalStateException("unsupported operand: " + operand.getClass());

try { boolean r = matcher.match(classLoader, operand, meta); } catch (IllegalArgumentException e) { log.error("matcher operand unsupported: {}", e.getMessage()); }

When it happens

Trigger: Calling match() with a custom or newly added MatcherOperand implementation not handled by the dispatcher, or a corrupted operand tree containing an unexpected node type.

Common situations: Extending the matcher framework with a new operand type but forgetting to add a branch in match(); pinning a plugin built against a newer pinpoint matcher API onto an older agent that lacks the operand type.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• BracketMatcherOperator is not an operation target.
• unsupported type:${dataType}
• source and advice class node must not be null.
• ${after} method not found. ${Arrays.toString(afterParamList)
• ${after} must return java.lang.Object. ${targetInterceptorCl

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