alibaba/spring-ai-alibaba · error · IllegalArgumentException

client cannot be null

Error message

client cannot be null

What it means

MongoSaver.Builder.build() validates that a MongoClient was supplied; if client is null it throws IllegalArgumentException('client cannot be null'). MongoSaver cannot function without a client connection, so this is a fail-fast constructor guard. If stateSerializer is null, a default Jackson serializer is used instead of throwing.

Solutions

1. Pass a client: MongoSaver.builder().client(mongoClient).build()
2. Verify the MongoClient bean exists and is injected before building the saver (check MongoClients.create(...) ran successfully)
3. If using Spring, confirm the MongoDB starter/connection config so the auto-configured client is available

Example fix

// before
MongoSaver saver = MongoSaver.builder().build(); // throws
// after
MongoClient client = MongoClients.create("mongodb://localhost:27017");
MongoSaver saver = MongoSaver.builder().client(client).build();

Objects.requireNonNull(mongoClient, "MongoClient must be created before MongoSaver.builder().build()");
MongoSaver saver = MongoSaver.builder().client(mongoClient).build();

boolean canBuildSaver(MongoClient client) {
    return client != null;
}

try {
    saver = MongoSaver.builder().client(client).build();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("client cannot be null")) {
        throw new IllegalStateException("MongoClient bean missing — check Mongo auto-configuration/connection properties", e);
    }
    throw e;
}

When it happens

Trigger: Calling MongoSaver.builder().build() without calling .client(...); a MongoClient field/bean that is null at build time (failed Spring bean wiring, @Autowired-by-constructor not yet injected, or configuration that skipped client creation).

Common situations: Misconfigured Spring context where the MongoClient bean wasn't created (missing spring-boot-starter-data-mongodb or connection properties); constructing the saver manually in a main() and forgetting the client; conditional bean creation that silently produced null.

Related errors

• AgentCard or AgentCardProvider must be provided
• At least one fallback model must be specified
• At least one sub-agent must be provided for flow
• ChatClient must not be null
• Description must be provided

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

Appendix: source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/checkpoint/savers/mongo/MongoSaver.java:544

		public Builder client(MongoClient client) {
			this.client = client;
			return this;
		}

		public Builder stateSerializer(StateSerializer stateSerializer) {
			this.stateSerializer = stateSerializer;
			return this;
		}

		/**
		 * Builds a new MongoSaver instance.
		 * @return a new MongoSaver instance
		 * @throws IllegalArgumentException if client or stateSerializer is null
		 */
		public MongoSaver build() {
			if (client == null) {
				throw new IllegalArgumentException("client cannot be null");
			}
			if (stateSerializer == null) {
				this.stateSerializer = StateGraph.DEFAULT_JACKSON_SERIALIZER;
			}
			return new MongoSaver(client, stateSerializer);
		}
	}

}

View on GitHub (pinned to f82da0b50f)