alibaba/spring-ai-alibaba · warning · IllegalArgumentException

cannot be null or empty

Error message

{fieldName} cannot be null or empty

What it means

FileSystemStore.validatePathSegment throws IllegalArgumentException('<field> cannot be null or empty') when a namespace element or key is null, empty, or whitespace-only. It is the first line of defense before path resolution in createItemPath.

Solutions

1. Validate namespace and key are non-blank before calling any store method
2. Check that each element of the namespace list is non-empty
3. Fix the upstream source of the empty value (config, request param, split result)
4. Apply a default key when the caller's id is missing

Example fix

// before
store.putItem(namespace, itemId, value); // itemId may be ""
// after
if (itemId == null || itemId.isBlank()) {
    throw new IllegalArgumentException("itemId is required");
}
store.putItem(namespace, itemId, value);

static void requireSegment(String v, String name) {
    if (v == null || v.isBlank()) throw new IllegalArgumentException(name + " required");
}
requireSegment(key, "key");
namespace == null || namespace.stream().forEach(n -> requireSegment(n, "namespace"));

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

try {
    store.putItem(ns, key, value);
} catch (IllegalArgumentException e) {
    logger.warn("rejected store argument: {}", e.getMessage());
}

When it happens

Trigger: store.putItem(null, key, value), store.getItem(ns, ""), a namespace list containing an empty string element, or a key of only spaces — any call where a path segment is blank.

Common situations: Downstream code returning empty optional IDs; config placeholders left unresolved (empty property); splitting strings that yield empty tokens; forgotten default values in application.yml.

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

• 数据项ID不能为空且必须大于0
• key cannot be empty
• key cannot be null
• key cannot be null or empty
• namespaceRequest cannot be null

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

Appendix: source

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

	 * @return item path
	 */
	private Path createItemPath(List<String> namespace, String key) {
		Path path = rootPath.toAbsolutePath().normalize();
		for (String ns : namespace) {
			validatePathSegment(ns, "namespace");
			path = path.resolve(ns);
		}
		validatePathSegment(key, "key");
		Path itemPath = path.resolve(key + ".json").normalize();
		if (!itemPath.startsWith(rootPath.toAbsolutePath().normalize())) {
			throw new IllegalArgumentException("resolved path escapes root directory");
		}
		return itemPath;
	}

	private void validatePathSegment(String segment, String fieldName) {
		if (segment == null || segment.trim().isEmpty()) {
			throw new IllegalArgumentException(fieldName + " cannot be null or empty");
		}
		Path candidate = Paths.get(segment);
		if (candidate.isAbsolute() || candidate.getNameCount() != 1 || "..".equals(segment) || ".".equals(segment)) {
			throw new IllegalArgumentException(fieldName + " contains unsafe path segment: " + segment);
		}
	}

	/**
	 * Ensure directory exists.
	 * @param directory directory to create
	 */
	private void ensureDirectoryExists(Path directory) throws IOException {
		if (!Files.exists(directory)) {
			Files.createDirectories(directory);
		}
	}

	/**

View on GitHub (pinned to f82da0b50f)