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

Ensure a non-null CallToolRequest is constructed (McpSchema.CallToolRequest.builder().name(toolName).arguments(args).build()) before invoking the callback.

spring-projects/spring-ai · error · IllegalArgumentException

Request must not be null

Error message

Request must not be null

What it means

AbstractSyncMcpToolMethodCallback.validateSyncRequest guards the entry of every synchronous MCP tool method callback. Before dispatching a @McpTool annotated method it verifies that the incoming McpAnnotationUtils-wrapped CallToolRequest is present; a null request cannot be executed, so an IllegalArgumentException is thrown immediately. This is an internal programming-contract check, not a user-input validation.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/method/tool/AbstractSyncMcpToolMethodCallback.java:89

	 * @return A CallToolResult representing the error
	 */
	protected CallToolResult createSyncErrorResult(Exception e) {
		Throwable rootCause = findCauseUsingPlainJava(e);
		return CallToolResult.builder()
			.isError(true)
			.addTextContent(e.getMessage() + System.lineSeparator() + rootCause.getMessage())
			.build();
	}

	/**
	 * Validates that the request is not null. This is a synchronous wrapper around the
	 * parent class's reactive validation.
	 * @param request The request to validate
	 * @throws IllegalArgumentException if the request is null
	 */
	protected void validateSyncRequest(CallToolRequest request) {
		if (request == null) {
			throw new IllegalArgumentException("Request must not be null");
		}
	}

}

View on GitHub (pinned to 98a7beda4f)

Solutions

Ensure a non-null CallToolRequest is constructed (McpSchema.CallToolRequest.builder().name(toolName).arguments(args).build()) before invoking the callback.
If calling from custom code, add a null check / Objects.requireNonNull on the request before dispatching to the tool callback.
Check for framework version alignment (spring-ai mcp modules all on the same version) so internal layers never pass null.

Example fix

// before
callback.call(context, null);

// after
McpSchema.CallToolRequest request = McpSchema.CallToolRequest.builder()
    .name("myTool")
    .arguments(Map.of("param", "value"))
    .build();
callback.call(context, request);

Defensive patterns

Strategy: validation

Validate before calling

if (request == null) {
    throw new IllegalArgumentException("CallToolRequest must be built before invoking the tool callback");
}

Prevention

Always construct CallToolRequest via its builder before invoking a tool callback.
Use Objects.requireNonNull at your dispatch layer's entry point.
Keep all spring-ai mcp module versions aligned to avoid internal null-passing regressions.

When it happens

Trigger: Calling any code path that invokes a sync MCP tool callback (e.g. call(McpTransportContext, CallToolRequest)) with a null CallToolRequest, or framework/transport layers that forward a missing request object.

Common situations: Custom transport or router code that builds tool-call invocations programmatically and forgets to construct the CallToolRequest; tests that call the callback directly with null; version mismatches where an upstream layer passes null after an API change.

Related errors

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