{"record":{"id":"3ba2d486d9fd6845","repo":"pinpoint-apm/pinpoint","slug":"unsupported-matcher-matcher","errorCode":null,"errorMessage":"unsupported matcher :${matcher}","messagePattern":"unsupported matcher :(.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/transformer/DefaultTransformerRegistry.java","lineNumber":89,"sourceCode":"    @Override\n    public ClassFileTransformer findTransformer(ClassLoader classLoader, String classInternalName, byte[] classFileBuffer, InternalClassMetadata classMetadata) {\n        return registry.get(classInternalName);\n    }\n\n    private void addTransformer(Map<String, ClassFileTransformer> registry, Matcher matcher, ClassFileTransformer transformer) {\n        // TODO extract matcher process\n        if (matcher instanceof ClassNameMatcher) {\n            final ClassNameMatcher classNameMatcher = (ClassNameMatcher) matcher;\n            String className = classNameMatcher.getClassName();\n            addModifier0(registry, transformer, className);\n        } else if (matcher instanceof MultiClassNameMatcher) {\n            final MultiClassNameMatcher classNameMatcher = (MultiClassNameMatcher) matcher;\n            List<String> classNameList = classNameMatcher.getClassNames();\n            for (String className : classNameList) {\n                addModifier0(registry, transformer, className);\n            }\n        } else {\n            throw new IllegalArgumentException(\"unsupported matcher :\" + matcher);\n        }\n    }\n\n    private void addModifier0(Map<String, ClassFileTransformer> registry, ClassFileTransformer transformer, String className) {\n        final String classInternalName = JavaAssistUtils.javaNameToJvmName(className);\n        final ClassFileTransformer old = registry.put(classInternalName, transformer);\n        if (old != null) {\n            throw new IllegalStateException(\"Transformer already exist. className:\" + classInternalName + \" new:\" + transformer.getClass() + \" old:\" + old.getClass());\n        }\n    }\n}","sourceCodeStart":71,"sourceCodeEnd":100,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/transformer/DefaultTransformerRegistry.java#L71-L100","documentation":"DefaultTransformerRegistry.addTransformer() only accepts matchers of a specific set of ClassFileTransformer-referencing matcher types (e.g. MultiClassNameMatcher); anything else is rejected with IllegalArgumentException. The registry indexes transformers by class name, so it can only register transformers whose class matcher it understands.","triggerScenarios":"Calling addTransformer(transformer, matcher) with a Matcher implementation outside the supported switch (not a known ClassNameMatcher/MultiClassNameMatcher type handled by addTransformer).","commonSituations":"Custom matcher implementation passed into the registry; API change across Pinpoint versions where a matcher type was removed or replaced.","solutions":["Use a supported matcher type (e.g. MultiClassNameMatcher) when calling addTransformer","Wrap custom class-name logic as a MultiClassNameMatcher with an explicit class-name list","Check the registry's supported matcher branches and extend addTransformer if a new matcher type must be supported"],"exampleFix":"// before\nregistry.addTransformer(transformer, myCustomMatcher);\n// after\nregistry.addTransformer(transformer, new MultiClassNameMatcher(Arrays.asList(\"com.example.Target\")));","handlingStrategy":"validation","validationCode":"if (!(matcher instanceof ClassNameMatcher) && !(matcher instanceof MultiClassNameMatcher)) {\n    throw new IllegalArgumentException(\"registry supports only (Multi)ClassNameMatcher, got: \" + matcher.getClass());\n}","typeGuard":"boolean isRegistryCompatible(Matcher m) {\n    return m instanceof ClassNameMatcher || m instanceof MultiClassNameMatcher;\n}","tryCatchPattern":"try {\n    registry.addTransformer(transformer, matcher);\n} catch (IllegalArgumentException e) {\n    logger.error(\"Unsupported matcher type: {}\", e.getMessage());\n}","preventionTips":["Stick to the matcher types documented for the registry","Wrap custom matching logic inside MultiClassNameMatcher","Check the registry source when upgrading Pinpoint versions"],"tags":["bytecode-instrumentation","illegal-argument","class-transformer"],"backgroundTag":"unsupported-operation","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}