{"record":{"id":"52f8f736ff869975","repo":"pinpoint-apm/pinpoint","slug":"unknown-operand-operand-operand","errorCode":null,"errorMessage":"unknown operand. operand=${operand}","messagePattern":"unknown operand\\. operand=(.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/transformer/DefaultTransformerMatcher.java","lineNumber":77,"sourceCode":"\n    public boolean match(ClassLoader classLoader, MatcherOperand operand, InternalClassMetadata classMetadata) {\n        if (operand.isOperator()) {\n            // operation\n            return traversal(classLoader, operand, classMetadata);\n        }\n\n        if (operand instanceof ClassInternalNameMatcherOperand) {\n            return matchClass((ClassInternalNameMatcherOperand) operand, classMetadata);\n        } else if (operand instanceof PackageInternalNameMatcherOperand) {\n            return matchPackage((PackageInternalNameMatcherOperand) operand, classMetadata);\n        } else if (operand instanceof InterfaceInternalNameMatcherOperand) {\n            return matchInterface(classLoader, (InterfaceInternalNameMatcherOperand) operand, classMetadata);\n        } else if (operand instanceof AnnotationInternalNameMatcherOperand) {\n            return matchAnnotation(classLoader, (AnnotationInternalNameMatcherOperand) operand, classMetadata);\n        } else if (operand instanceof SuperClassInternalNameMatcherOperand) {\n            return matchSuper(classLoader, (SuperClassInternalNameMatcherOperand) operand, classMetadata);\n        } else {\n            throw new IllegalArgumentException(\"unknown operand. operand=\" + operand);\n        }\n    }\n\n    boolean matchClass(final ClassInternalNameMatcherOperand operand, final InternalClassMetadata classMetadata) {\n        if (classMetadata == null) {\n            return false;\n        }\n        if (classMetadata.isInterface() || classMetadata.isAnnotation()) {\n            // skip interface and annotation.\n            return false;\n        }\n        return operand.match(classMetadata.getClassInternalName());\n    }\n\n    boolean matchPackage(final PackageInternalNameMatcherOperand operand, final InternalClassMetadata classMetadata) {\n        if (classMetadata == null) {\n            return false;\n        }","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/transformer/DefaultTransformerMatcher.java#L59-L95","documentation":"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'.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add an instanceof branch in match() handling the unknown operand type","Use a supported operand type (Class/Interface/Annotation/SuperClassInternalNameMatcherOperand)","Rebuild the plugin against the agent's matcher API version so operand classes align"],"exampleFix":"// before\n} else {\n    throw new IllegalArgumentException(\"unknown operand. operand=\" + operand);\n}\n// after\n} else if (operand instanceof MyCustomOperand) {\n    return matchCustom(classLoader, (MyCustomOperand) operand, classMetadata);\n} else {\n    throw new IllegalArgumentException(\"unknown operand. operand=\" + operand);\n}","handlingStrategy":"validation","validationCode":"if (!(operand instanceof ClassInternalNameMatcherOperand || operand instanceof InterfaceInternalNameMatcherOperand || operand instanceof AnnotationInternalNameMatcherOperand || operand instanceof SuperClassInternalNameMatcherOperand)) throw new IllegalStateException(\"unsupported operand: \" + operand.getClass());","typeGuard":null,"tryCatchPattern":"try { boolean r = matcher.match(classLoader, operand, meta); } catch (IllegalArgumentException e) { log.error(\"matcher operand unsupported: {}\", e.getMessage()); }","preventionTips":["Only use built-in operand types","Add a dispatch branch for any custom operand","Keep plugin and agent matcher API versions aligned"],"tags":["java","matcher","instrumentation","unsupported-type","dispatch"],"backgroundTag":"unsupported-operation","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"}