alibaba/spring-ai-alibaba · error · IllegalArgumentException

key cannot be null

Error message

key cannot be null

What it means

BaseStore.validateGetItem rejects a null key when reading a store item. The store requires both a namespace and a non-null, non-empty key to locate an item, so a null key is an invalid argument for getItem. This guards subclasses against constructing malformed storage lookups.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/store/stores/BaseStore.java:70

		if (item.getNamespace() == null) {
			throw new IllegalArgumentException("namespace cannot be null");
		}
		if (item.getKey() == null || item.getKey().trim().isEmpty()) {
			throw new IllegalArgumentException("key cannot be null or empty");
		}
	}

	/**
	 * Validates the getItem parameters.
	 * @param namespace namespace
	 * @param key key
	 */
	protected void validateGetItem(List<String> namespace, String key) {
		if (namespace == null) {
			throw new IllegalArgumentException("namespace cannot be null");
		}
		if (key == null) {
			throw new IllegalArgumentException("key cannot be null");
		}
		if (key.trim().isEmpty()) {
			throw new IllegalArgumentException("key cannot be empty");
		}
	}

	/**
	 * Validates the deleteItem parameters.
	 * @param namespace namespace
	 * @param key key
	 */
	protected void validateDeleteItem(List<String> namespace, String key) {
		if (namespace == null) {
			throw new IllegalArgumentException("namespace cannot be null");
		}
		if (key == null) {
			throw new IllegalArgumentException("key cannot be null");
		}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Ensure a non-null key is passed to getItem; check the value before the call.
2. If the key comes from a Map/JSON lookup, use getOrDefault or validate presence first.
3. Wrap the call in try-catch for IllegalArgumentException if null keys are possible and handle them explicitly.

Example fix

// before
store.getItem(List.of("users"), params.get("key"));
// after
String key = params.get("key");
if (key == null || key.isBlank()) {
    throw new IllegalArgumentException("item key is required");
}
store.getItem(List.of("users"), key);

if (key == null || key.isBlank()) {
    throw new IllegalArgumentException("store item key is required");
}
store.getItem(namespace, key);

boolean hasKey(String k) { return k != null && !k.isBlank(); }

try {
    store.getItem(namespace, key);
} catch (IllegalArgumentException e) {
    // key/namespace invalid
    log.warn("Invalid store lookup: {}", e.getMessage());
}

When it happens

Trigger: Calling store.getItem(namespace, null) or passing a variable that is null (e.g. a map lookup result or an unset field) as the key argument to getItem on any BaseStore subclass.

Common situations: Extracting the key from user input, JSON payloads, or a Map.get() that returns null when the entry is absent; refactoring code that renamed a config field so the key variable is no longer populated.

Related errors

• searchRequest cannot be null
• namespaceRequest cannot be null
• key cannot be null or empty
• key cannot be empty
• TOOL_PARAMS_MISSING

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