What causes "Bean must not be null" in spring-projects/spring-ai?

Call .bean(Object) on the builder with the instance that owns the annotated method.

spring-projects/spring-ai · error · java.lang.IllegalArgumentException

Bean must not be null

Error message

Bean must not be null

What it means

The builder for McpProgress method callbacks requires a target bean (the object instance whose method will be invoked). validate() throws this IllegalArgumentException when the builder's bean field is null at build() time. Without a bean the callback has no instance to invoke the validated Method on.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/method/progress/AbstractMcpProgressMethodCallback.java:240

		 * @param progress The progress annotation
		 * @return This builder
		 */
		@SuppressWarnings("unchecked")
		public T progress(McpProgress progress) {
			// No additional configuration needed from the annotation at this time
			return (T) this;
		}

		/**
		 * Validate the builder state.
		 * @throws IllegalArgumentException if the builder state is invalid
		 */
		protected void validate() {
			if (this.method == null) {
				throw new IllegalArgumentException("Method must not be null");
			}
			if (this.bean == null) {
				throw new IllegalArgumentException("Bean must not be null");
			}
		}

		/**
		 * Build the callback.
		 * @return A new callback instance
		 */
		public abstract R build();

	}

}

View on GitHub (pinned to 98a7beda4f)

Solutions

Call .bean(Object) on the builder with the instance that owns the annotated method.
Fix bean retrieval (e.g. applicationContext.getBean(...)) so it returns a non-null instance.
Verify Spring wiring/scanning so the handler bean is actually created before registration.

Example fix

// before
var callback = AsyncMcpProgressMethodCallback.builder()
    .method(m).build();
// after
var callback = AsyncMcpProgressMethodCallback.builder()
    .method(m).bean(progressHandlerBean).build();

Defensive patterns

Strategy: validation

Validate before calling

Objects.requireNonNull(bean, "target bean must be provided");
var cb = AsyncMcpProgressMethodCallback.builder().method(method).bean(bean).build();

Type guard

function requiresBean(b) { if (b == null || b.bean == null) throw new Error('builder.bean() not set'); return b; }

Try / catch

try {
    return builder.method(method).build();
} catch (IllegalArgumentException e) {
    if ("Bean must not be null".equals(e.getMessage())) {
        throw new IllegalStateException("bean not injected — check Spring wiring/scanning", e);
    }
    throw e;
}

Prevention

Always chain .method(...).bean(...) together in a helper factory method.
Verify the handler bean exists in the application context before registration.
Use constructor injection so the bean reference cannot be null.

When it happens

Trigger: Calling AsyncMcpProgressMethodCallback.builder().method(m).build() without calling .bean(instance), or passing a null bean reference obtained from a failed lookup/injection.

Common situations: Manual (non-Spring) registration where the developer forgets the bean; a Spring bean injection field that is null because component scanning missed the class; test code constructing builders directly.

Related errors

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/33ede3d889cefc15. Report an issue: GitHub.