spring-projects/spring-ai · error · IllegalArgumentException

Bean must not be null

Error message

Bean must not be null

What it means

Builder-state validation error thrown when the target bean (the object holding the @McpResource method) is null when building an AbstractMcpResourceMethodCallback. The framework needs the bean instance to invoke the method on.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/method/resource/AbstractMcpResourceMethodCallback.java:723

		 * Set the MIME type of the resource.
		 * @param mimeType The MIME type of the resource
		 * @return This builder
		 */
		public T mimeType(String mimeType) {
			this.mimeType = mimeType;
			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");
			}
			if (this.uri == null || this.uri.isEmpty()) {
				throw new IllegalArgumentException("URI must not be null or empty");
			}
			if (this.uriTemplateManagerFactory == null) {
				this.uriTemplateManagerFactory = new DefaultMcpUriTemplateManagerFactory();
			}
			if (this.mimeType == null) {
				this.mimeType = "text/plain";
			}

			if (this.name == null) {
				this.name = this.method.getName();
			}
		}

		/**
		 * Build the callback.

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Pass the handler instance: .bean(handlerObject) before build()
2. Verify the bean is injected/constructed before MCP registration runs (check @Autowired/@Component wiring)
3. Assert non-null in your registration code and fail early with a clear message

Example fix

// before
McpSyncResourceMethodCallback.builder().method(m).uri("docs/{id}").build();
// after
McpSyncResourceMethodCallback.builder().bean(myResourceHandler).method(m).uri("docs/{id}").build();

Objects.requireNonNull(bean, "bean must be set on the resource callback builder");

if (handler == null) { throw new IllegalStateException("Handler bean not injected before MCP registration"); }

try {
    var cb = builder().bean(bean).method(method).uri(uri).build();
} catch (IllegalArgumentException e) {
    if (e.getMessage().equals("Bean must not be null")) throw new IllegalStateException("Builder misconfiguration: set .bean(...)", e);
    throw e;
}

When it happens

Trigger: Calling builder().method(m).uri(u).build() without .bean(...) — typically in programmatic registration where the bean instance wasn't resolved or a dependency was null.

Common situations: Manual registration in tests with a null bean; Spring bean not yet injected (field null at registration time); component scanned incorrectly so the handler object is missing.

Related errors

• URI must not be null or empty
• Method must have exactly 1 parameter (List<McpSchema.Resourc
• Bean must not be null
• Method must have void or Mono<Void> return type:
• Updated resources list must not be null

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