alibaba/spring-ai-alibaba · error · IllegalArgumentException

ChatClient must not be null

Error message

ChatClient must not be null

What it means

WebFetchTool.Builder's package-private constructor requires a non-null ChatClient (the tool uses it to summarize/process fetched content). Passing null throws IllegalArgumentException('ChatClient must not be null') at construction time — a fail-fast programming-error guard.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/tools/WebFetchTool.java:426

	}

	public static class Builder {

		private final ChatClient chatClient;

		private int maxContentLength = 100_000;

		private int maxCacheSize = 100;

		private int maxRetries = 2;

		private String name = "web_fetch";

		private String description = DEFAULT_TOOL_DESCRIPTION;

		private Builder(ChatClient chatClient) {
			if (chatClient == null) {
				throw new IllegalArgumentException("ChatClient must not be null");
			}
			this.chatClient = chatClient;
		}

		public Builder maxContentLength(int maxContentLength) {
			if (maxContentLength <= 0) {
				throw new IllegalArgumentException("maxContentLength must be positive");
			}
			this.maxContentLength = maxContentLength;
			return this;
		}

		public Builder maxCacheSize(int maxCacheSize) {
			if (maxCacheSize <= 0) {
				throw new IllegalArgumentException("maxCacheSize must be positive");
			}
			this.maxCacheSize = maxCacheSize;
			return this;

View on GitHub (pinned to f82da0b50f)

Solutions

1. Pass a properly built ChatClient, e.g. ChatClient.builder(chatModel).build().
2. Ensure the ChatClient bean is injected before the tool is constructed (constructor injection).
3. Add a null check or @AssertNonNull in your configuration class before builder() call.
4. If the bean may be absent, make the tool creation conditional (@ConditionalOnBean).

Example fix

// before
WebFetchTool.builder(null).build();
// after
ChatClient chatClient = ChatClient.builder(chatModel).build();
WebFetchTool tool = WebFetchTool.builder(chatClient).build();

if (chatClient == null) {
    throw new IllegalStateException("ChatClient bean must be initialized before building WebFetchTool");
}
WebFetchTool tool = WebFetchTool.builder(chatClient).build();

boolean hasChatClient(ChatClient c) { return c != null; }

try {
    tool = WebFetchTool.builder(chatClient).build();
} catch (IllegalArgumentException e) {
    if ("ChatClient must not be null".equals(e.getMessage())) {
        throw new BeanInitializationException("ChatClient missing; wire chatModel first", e);
    }
    throw e;
}

When it happens

Trigger: Calling WebFetchTool.builder(null), or passing a ChatClient field/bean that has not been initialized (still null) at wiring time.

Common situations: Forgetting to @Autowired or inject the ChatClient bean; constructing the tool in a static initializer before the Spring context is ready; refactoring that removed the client assignment.

Related errors

• SkillRegistry cannot be null
• SkillRegistry cannot be null
• SkillRegistry cannot be null
• At least one fallback model must be specified
• maxAttempts must be greater than or equal to 1

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/3e4b724fdc3dd4a0. Report an issue: GitHub.