pinpoint-apm/pinpoint · error · IllegalArgumentException

unsupported matcher

Error message

unsupported matcher :${matcher}

What it means

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.

Solutions

1. Use a supported matcher type (e.g. MultiClassNameMatcher) when calling addTransformer
2. Wrap custom class-name logic as a MultiClassNameMatcher with an explicit class-name list
3. Check the registry's supported matcher branches and extend addTransformer if a new matcher type must be supported

Example fix

// before
registry.addTransformer(transformer, myCustomMatcher);
// after
registry.addTransformer(transformer, new MultiClassNameMatcher(Arrays.asList("com.example.Target")));

if (!(matcher instanceof ClassNameMatcher) && !(matcher instanceof MultiClassNameMatcher)) {
    throw new IllegalArgumentException("registry supports only (Multi)ClassNameMatcher, got: " + matcher.getClass());
}

boolean isRegistryCompatible(Matcher m) {
    return m instanceof ClassNameMatcher || m instanceof MultiClassNameMatcher;
}

try {
    registry.addTransformer(transformer, matcher);
} catch (IllegalArgumentException e) {
    logger.error("Unsupported matcher type: {}", e.getMessage());
}

When it happens

Trigger: Calling addTransformer(transformer, matcher) with a Matcher implementation outside the supported switch (not a known ClassNameMatcher/MultiClassNameMatcher type handled by addTransformer).

Common situations: Custom matcher implementation passed into the registry; API change across Pinpoint versions where a matcher type was removed or replaced.

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

• unknown operator. operator=
• Ignore class file transformer
• Transformer already exist. className
• agentStartTimeIndex not found
• application serviceType not found. code:, name:

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

Appendix: source

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

    @Override
    public ClassFileTransformer findTransformer(ClassLoader classLoader, String classInternalName, byte[] classFileBuffer, InternalClassMetadata classMetadata) {
        return registry.get(classInternalName);
    }

    private void addTransformer(Map<String, ClassFileTransformer> registry, Matcher matcher, ClassFileTransformer transformer) {
        // TODO extract matcher process
        if (matcher instanceof ClassNameMatcher) {
            final ClassNameMatcher classNameMatcher = (ClassNameMatcher) matcher;
            String className = classNameMatcher.getClassName();
            addModifier0(registry, transformer, className);
        } else if (matcher instanceof MultiClassNameMatcher) {
            final MultiClassNameMatcher classNameMatcher = (MultiClassNameMatcher) matcher;
            List<String> classNameList = classNameMatcher.getClassNames();
            for (String className : classNameList) {
                addModifier0(registry, transformer, className);
            }
        } else {
            throw new IllegalArgumentException("unsupported matcher :" + matcher);
        }
    }

    private void addModifier0(Map<String, ClassFileTransformer> registry, ClassFileTransformer transformer, String className) {
        final String classInternalName = JavaAssistUtils.javaNameToJvmName(className);
        final ClassFileTransformer old = registry.put(classInternalName, transformer);
        if (old != null) {
            throw new IllegalStateException("Transformer already exist. className:" + classInternalName + " new:" + transformer.getClass() + " old:" + old.getClass());
        }
    }
}

View on GitHub (pinned to 744c3d3075)