What causes "Illegal MethodMatcher usage" in spring-projects/spring-framework?

Call the 2-arg matches(Method, Class) on a StaticMethodMatcher — never the 3-arg runtime overload.

spring-projects/spring-framework · error · UnsupportedOperationException

Illegal MethodMatcher usage

Error message

Illegal MethodMatcher usage

What it means

Thrown by StaticMethodMatcher.matches(Method, Class, Object...) — the 3-argument runtime overload. StaticMethodMatcher.isRuntime() is final and returns false, meaning the matcher does not evaluate at runtime with argument values; the 3-arg matches is therefore final and throws UnsupportedOperationException because it should never be called by the framework.

Solutions

Call the 2-arg matches(Method, Class) on a StaticMethodMatcher — never the 3-arg runtime overload.
Before invoking the runtime overload, guard with matcher.isRuntime(); only call 3-arg matches when it returns true.
If you truly need runtime argument matching, subclass DynamicMethodMatcher instead of StaticMethodMatcher.

Example fix

// before
StaticMethodMatcher m = ...;
m.matches(method, targetClass, args); // throws

// after
if (m.isRuntime()) { m.matches(method, targetClass, args); }
else { m.matches(method, targetClass); }

Defensive patterns

Strategy: type-guard

Validate before calling

MethodMatcher m = ...;
if (m.isRuntime()) {
    m.matches(method, targetClass, args);
} else {
    m.matches(method, targetClass);
}

Type guard

static boolean isRuntimeMatcher(MethodMatcher m) { return m.isRuntime(); }

Try / catch

try {
    matcher.matches(method, targetClass, args);
} catch (UnsupportedOperationException ex) {
    // matcher is static; fall back to 2-arg matches
    matcher.matches(method, targetClass);
}

Prevention

Always gate the 3-arg matches on matcher.isRuntime().
Use StaticMethodMatcher only when you never need argument values; otherwise extend DynamicMethodMatcher.
In custom pointcut frameworks, branch on isRuntime() before dispatching.

When it happens

Trigger: Directly invoking the 3-arg matches(method, targetClass, args) on an instance of a StaticMethodMatcher subclass; or a custom pointcut/advisor framework incorrectly dispatching the runtime variant without checking isRuntime().

Common situations: Third-party AOP code or a test calling the wrong matches overload; upgrading Spring versions where the method became final; writing a custom MethodMatcher delegate that forwards to a static matcher with the 3-arg signature.

Related errors

AI-assisted analysis of spring-projects/spring-framework@69bf83ad71 (2026-08-09). Data as JSON: /api/errors/1ea0391185cb5402. Report an issue: GitHub.

Appendix: source

Thrown at spring-aop/src/main/java/org/springframework/aop/support/StaticMethodMatcher.java:41

import org.springframework.aop.MethodMatcher;

/**
 * Convenient abstract superclass for static method matchers, which don't care
 * about arguments at runtime.
 *
 * @author Rod Johnson
 */
public abstract class StaticMethodMatcher implements MethodMatcher {

	@Override
	public final boolean isRuntime() {
		return false;
	}

	@Override
	public final boolean matches(Method method, Class<?> targetClass, @Nullable Object... args) {
		// should never be invoked because isRuntime() returns false
		throw new UnsupportedOperationException("Illegal MethodMatcher usage");
	}

}

View on GitHub (pinned to 69bf83ad71)