alibaba/spring-ai-alibaba · error · IllegalArgumentException

item cannot be null

Error message

item cannot be null

What it means

BaseStore.validatePutItem rejects a null StoreItem passed to putItem with IllegalArgumentException. The store API requires a fully populated item object; a null item cannot be persisted or validated field-by-field.

Source

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

 * Abstract base class for Store implementations providing common validation and utility
 * methods.
 * <p>
 * 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");
		}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Construct a StoreItem before calling putItem
2. Null-check the item (or Objects.requireNonNull) before calling the store
3. Fix the producing code that returns null instead of an item

Example fix

// before
StoreItem item = fetchItem(); // may return null
store.putItem(item);
// after
StoreItem item = fetchItem();
if (item != null) {
    store.putItem(item);
}

if (item == null) { throw new IllegalArgumentException("item required before putItem"); }

boolean isPutable(StoreItem i) { return i != null && i.getNamespace() != null && i.getKey() != null && !i.getKey().isBlank(); }

try { store.putItem(item); } catch (IllegalArgumentException e) { log.warn("putItem rejected: {}", e.getMessage()); }

When it happens

Trigger: Calling store.putItem(null) directly, or building the item in a conditional branch that never assigned it (e.g. Optional/nullable producer returned null).

Common situations: Factory method returning null when no data was available; map lookup for the item returning null; forgetting to construct the item after computing namespace/key.

Related errors

• namespace cannot be null
• SkillRegistry cannot be null
• SkillRegistry cannot be null
• SkillRegistry cannot be null
• Skill name cannot be null or empty

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