spring-projects/spring-framework · error · IllegalStateException

Returning argument name '{}' was not bound in advice argumen

Error message

Returning argument name '{}' was not bound in advice arguments

What it means

Thrown by bindExplicitArguments (line 486-490) when returningName is set but does not appear as a key in argumentBindings, i.e. no advice parameter carries that name. After setting a 'returning' binding, Spring requires a matching parameter to receive the return value.

Source

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

		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 {
				Integer index = this.argumentBindings.get(this.returningName);
				this.discoveredReturningType = this.aspectJAdviceMethod.getParameterTypes()[index];
				this.discoveredReturningGenericType = this.aspectJAdviceMethod.getGenericParameterTypes()[index];
			}
		}
		if (this.throwingName != null) {
			if (!this.argumentBindings.containsKey(this.throwingName)) {
				throw new IllegalStateException("Throwing argument name '" + this.throwingName +
						"' was not bound in advice arguments");
			}
			else {
				Integer index = this.argumentBindings.get(this.throwingName);
				this.discoveredThrowingType = this.aspectJAdviceMethod.getParameterTypes()[index];
			}
		}

View on GitHub (pinned to e8729d0438)

Solutions

1. Make the 'returning' value exactly match the name of an advice parameter (and include it in arg-names if you supply arg-names).
2. Add the missing parameter to the advice method so the returning name binds.
3. Compile with -parameters or specify arg-names consistently so the names line up.
4. If you do not need to bind the return value, remove the returning attribute.

Example fix

// before
@AfterReturning(value = "...", returning = "ret")
public void log(Object result) { ... }
// after
@AfterReturning(value = "...", returning = "ret")
public void log(Object ret) { ... }

// Ensure the returning name corresponds to an actual parameter name.
Set<String> paramNames = Set.of(new DefaultParameterNameDiscoverer().getParameterNames(adviceMethod));
if (returningName != null && !paramNames.contains(returningName)) {
    throw new IllegalStateException(
        "returning='" + returningName + "' is not among advice parameters " + paramNames);
}

When it happens

Trigger: The 'returning' attribute names a value that is not among the advice method's parameter names (and arg-names), or the parameter was omitted from arg-names. E.g. returning="ret" but the advice method's parameter is named 'result' and no arg-names aliasing is provided.

Common situations: Renaming the advice parameter without updating the returning attribute; returning attribute referencing a name that doesn't exist; case/typo mismatch between returning and the actual parameter name.

Related errors

• 'argumentNames' property of AbstractAspectJAdvice contains a
• Only afterReturning advice can be used to bind a return valu
• Returning name '{}' is neither a valid argument name nor the
• Advice method [{}] requires {} arguments to be bound by name
• Expecting to find {} arguments to bind by name in advice, bu

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