alibaba/spring-ai-alibaba · error · IllegalArgumentException

key cannot be null or empty

Error message

key cannot be null or empty

What it means

validatePutItem requires the item's key to be non-null and non-blank; a key that is null, empty, or whitespace-only causes IllegalArgumentException because the key uniquely identifies the item within its namespace.

Source

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

 *
 * @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");
		}
		if (key.trim().isEmpty()) {
			throw new IllegalArgumentException("key cannot be empty");
		}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Provide a non-blank key when constructing StoreItem
2. Use StringUtils.hasText (Spring) or key != null && !key.isBlank() to validate before putItem
3. Add builder-level validation so items with blank keys cannot be constructed

Example fix

// before
StoreItem item = StoreItem.builder().namespace(ns).key("").value(v).build();
store.putItem(item);
// after
if (key != null && !key.isBlank()) {
    store.putItem(StoreItem.builder().namespace(ns).key(key).value(v).build());
}

if (key == null || key.isBlank()) { throw new IllegalArgumentException("key required"); }

boolean hasText(String s) { return s != null && !s.isBlank(); }

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

When it happens

Trigger: Building a StoreItem whose key comes from an empty string, blank user input, or an unset variable, then calling store.putItem(item).

Common situations: Key derived from a config field that is empty; trimming user input already done so a whitespace-only key slips through; forgetting to set key in the builder.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• key cannot be null
• key cannot be empty
• searchRequest cannot be null
• namespaceRequest cannot be null
• Elastic search index name must be provided

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