alibaba/spring-ai-alibaba · error · RuntimeException

Failed to create store key

Error message

Failed to create store key

What it means

createStoreKey encodes {namespace, key} as JSON and Base64; if serialization fails for any reason it wraps the exception in RuntimeException("Failed to create store key"). This is an internal encoding step, so failure usually indicates an unexpected problem (e.g. JSON serialization of the namespace/key data).

Solutions

1. Inspect the wrapped cause (e.getCause()) to find the real serialization failure.
2. Verify namespace and key contain normal strings without control characters; sanitize inputs.
3. Retry the operation if the cause is transient; otherwise report it as a library bug with the cause chain.

if (namespace == null || key == null || key.isBlank()) {
    throw new IllegalArgumentException("namespace and non-blank key required");
}

try {
    store.getItem(namespace, key);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("Failed to create store key")) {
        throw new IllegalStateException("Store key encoding failed: " + e.getCause(), e);
    }
    throw e;
}

When it happens

Trigger: Any getItem/putItem/deleteItem call where Base64 encoding of the JSON-serialized keyData throws — practically rare since inputs are List<String> and String, but possible via an ObjectMapper construction/serialization failure.

Common situations: Odd characters or extremely large namespaces triggering serializer limits; environments where a custom ObjectMapper/JSON provider conflicts; wrapped low-level IOException surfaced during store operations.

Understand the failure class

Background: json.Marshal / "failed to marshal" errors in Go: why "unsupported type" happens and how to fix it — this error's family across 22 libraries.

Related errors

• Failed to parse store key
• item cannot be null
• key cannot be empty
• key 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/fc65e7a3629b6274. Report an issue: GitHub.

Appendix: source

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

		}
	}

	/**
	 * Create store key from namespace and key Uses safe encoding to avoid conflicts from
	 * special characters.
	 * @param namespace namespace
	 * @param key key
	 * @return store key
	 */
	protected String createStoreKey(List<String> namespace, String key) {
		try {
			Map<String, Object> keyData = new HashMap<>();
			keyData.put("namespace", namespace);
			keyData.put("key", key);
			return Base64.getEncoder().encodeToString(new ObjectMapper().writeValueAsBytes(keyData));
		}
		catch (Exception e) {
			throw new RuntimeException("Failed to create store key", e);
		}
	}

	/**
	 * Parse store key to namespace and key.
	 * @param storeKey store key
	 * @return array containing [namespace, key]
	 */
	@SuppressWarnings("unchecked")
	protected Object[] parseStoreKey(String storeKey) {
		try {
			byte[] decoded = Base64.getDecoder().decode(storeKey);
			Map<String, Object> keyData = new ObjectMapper().readValue(decoded, Map.class);
			List<String> namespace = (List<String>) keyData.get("namespace");
			String key = (String) keyData.get("key");
			return new Object[] { namespace, key };
		}
		catch (Exception e) {

View on GitHub (pinned to f82da0b50f)