spring-projects/spring-framework · error · IllegalStateException

Expecting to find {} arguments to bind by name in advice, bu

Error message

Expecting to find {} arguments to bind by name in advice, but actually found {} arguments.

What it means

Thrown by bindExplicitArguments (line 471-476) when the number of argumentNames does not equal the advice method's parameter count. Spring requires a 1:1 correspondence (with the implicit join-point name injected where applicable) before it can build the argumentBindings map.

Source

Thrown at spring-aop/src/main/java/org/springframework/aop/aspectj/AbstractAspectJAdvice.java:473

		DefaultParameterNameDiscoverer discoverer = new DefaultParameterNameDiscoverer();
		AspectJAdviceParameterNameDiscoverer adviceParameterNameDiscoverer =
				new AspectJAdviceParameterNameDiscoverer(this.pointcut.getExpression());
		adviceParameterNameDiscoverer.setReturningName(this.returningName);
		adviceParameterNameDiscoverer.setThrowingName(this.throwingName);
		// Last in chain, so if we're called and we fail, that's bad...
		adviceParameterNameDiscoverer.setRaiseExceptions(true);
		discoverer.addDiscoverer(adviceParameterNameDiscoverer);
		return discoverer;
	}

	@SuppressWarnings("NullAway") // Dataflow analysis limitation
	private void bindExplicitArguments(int numArgumentsLeftToBind) {
		Assert.state(this.argumentNames != null, "No argument names available");
		this.argumentBindings = new HashMap<>();

		int numExpectedArgumentNames = this.aspectJAdviceMethod.getParameterCount();
		if (this.argumentNames.length != numExpectedArgumentNames) {
			throw new IllegalStateException("Expecting to find " + numExpectedArgumentNames +
					" arguments to bind by name in advice, but actually found " +
					this.argumentNames.length + " arguments.");
		}

		// So we match in number...
		int argumentIndexOffset = this.parameterTypes.length - numArgumentsLeftToBind;
		for (int i = argumentIndexOffset; i < this.argumentNames.length; i++) {
			this.argumentBindings.put(this.argumentNames[i], i);
		}

		// Check that returning and throwing were in the argument names list if
		// specified, and find the discovered argument types.
		if (this.returningName != null) {
			if (!this.argumentBindings.containsKey(this.returningName)) {
				throw new IllegalStateException("Returning argument name '" + this.returningName +
						"' was not bound in advice arguments");
			}
			else {

View on GitHub (pinned to e8729d0438)

Solutions

1. Make arg-names list exactly one name per advice method parameter (including any join-point/returning/throwing params).
2. If a JoinPoint/ProceedingJoinPoint/StaticPart param is present, note Spring may inject 'THIS_JOIN_POINT' automatically only when the count is off by exactly one (see line 273); otherwise align counts manually.
3. Remove arg-names and let discovery work (compile with -parameters) when unsure.
4. Recount parameters after any signature change and update arg-names in lockstep.

Example fix

// before: method has 2 params, only 1 name given
@AfterReturning(value = "args(req)", returning = "ret", argNames = "req")
public void log(Object req, Object ret) { ... }
// after
@AfterReturning(value = "args(req)", returning = "ret", argNames = "req,ret")
public void log(Object req, Object ret) { ... }

// Verify arg-names count equals parameter count before passing it in.
String[] tokens = argNames.split(",");
if (tokens.length != adviceMethod.getParameterCount()) {
    throw new IllegalStateException("arg-names has " + tokens.length
        + " tokens but the advice method declares " + adviceMethod.getParameterCount());
}

When it happens

Trigger: Providing arg-names with the wrong count: fewer or more names than the advice method declares parameters; forgetting to account for a JoinPoint/ProceedingJoinPoint/StaticPart parameter; supplying names for returning/throwing parameters inconsistently.

Common situations: Editing an advice method signature (adding/removing a param) without updating arg-names; miscounting because of an implicit join-point parameter; copy-paste between advice methods with different arities.

Related errors

• Not enough arguments in method to satisfy binding of returni
• 'argumentNames' property of AbstractAspectJAdvice contains a
• Advice method [{}] requires {} arguments to be bound by name
• Returning argument name '{}' was not bound in advice argumen
• Throwing argument name '{}' was not bound in advice argument

AI-assisted analysis of spring-projects/spring-framework@e8729d0438 (2026-08-04). Data as JSON: /data/errors/8b86c2d5f88ea47e.json. Report an issue: GitHub.