alibaba/spring-ai-alibaba · error · IllegalArgumentException

namespace cannot be null

Error message

namespace cannot be null

What it means

Generic validation guard in BaseStore.validatePutItem, the shared preconditions helper implemented by all Store implementations. A StoreItem must have a namespace to be addressable; when StoreItem.getNamespace() is null the item is malformed for storage and IllegalArgumentException is thrown before any backend write occurs. The same helper also rejects null items and null/blank keys. Callers should construct StoreItem with a non-null namespace.

Source

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

 * This class offers a foundation for implementing the Store interface with consistent
 * validation behavior and common helper methods.
 * </p>
 *
 * @author Spring AI Alibaba
 * @since 1.0.0.3
 */
public abstract class BaseStore implements Store {

	/**
	 * Validates the putItem parameters.
	 * @param item the item to validate
	 */
	protected void validatePutItem(StoreItem item) {
		if (item == null) {
			throw new IllegalArgumentException("item cannot be null");
		}
		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");
		}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Set a namespace (even empty list semantics per API docs) when building StoreItem
2. Validate item.getNamespace() != null before putItem
3. Check deserialization/builder code that drops the namespace field

Example fix

// before
StoreItem item = StoreItem.builder().key("k").value(v).build();
store.putItem(item);
// after
StoreItem item = StoreItem.builder().namespace(List.of("users")).key("k").value(v).build();
store.putItem(item);

if (item == null || item.getNamespace() == null) { /* fix before putItem */ }

try { store.putItem(item); } catch (IllegalArgumentException e) { log.warn("namespace missing on item", e); }

When it happens

Trigger: Creating a StoreItem via a builder/constructor that leaves namespace unset, or constructing the item manually with a null namespace list, then calling store.putItem(item).

Common situations: Omitting the namespace when building the item from user/config data; deserializing an item from JSON where the namespace field was absent; a default constructor path that skips namespace.

Related errors

• item cannot be null
• SkillRegistry cannot be null
• SkillRegistry cannot be null
• SkillRegistry cannot be null
• key cannot be null or empty

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