spring-projects/spring-ai · error · IllegalArgumentException

Not allowed filter identifier name: . Consider adding it to…

Error message

Not allowed filter identifier name: . Consider adding it to WeaviateVectorStore#filterMetadataKeys.

What it means

Weaviate restricts filterable fields to those registered via WeaviateVectorStore#filterMetadataKeys; withMetaPrefix only maps an identifier if it is in that allowed set, otherwise it throws this IllegalArgumentException. This whitelisting prevents querying unindexed (and therefore unusable) metadata fields and injection-style key names.

Solutions

1. Add the field to filterMetadataKeys when building the store: WeaviateVectorStore.builder(...).filterMetadataKeys(List.of("category"))...
2. Check for typos/case mismatches between the filter key and the registered whitelist entry.
3. If the field genuinely shouldn't be filtered, rewrite the query to filter on a registered field.

Example fix

// before
WeaviateVectorStore store = WeaviateVectorStore.builder(weaviateClient).build();
// after
WeaviateVectorStore store = WeaviateVectorStore.builder(weaviateClient)
    .filterMetadataKeys(List.of("category", "author"))
    .build();

if (!registeredFilterMetadataKeys.contains(metadataKey)) throw new IllegalArgumentException(metadataKey + " not in filterMetadataKeys");

try { vectorStore.similaritySearch(req); } catch (IllegalArgumentException e) { if (e.getMessage().contains("filterMetadataKeys")) { /* add key to whitelist and rebuild store */ } else throw e; }

When it happens

Trigger: Running a similaritySearch with a filter Key whose metadata field was never added to filterMetadataKeys when the WeaviateVectorStore was built, e.g. filtering on 'category' while the builder only listed 'author'.

Common situations: Forgetting to call filterMetadataKeys(...) on the builder for new metadata fields; renaming metadata keys in documents without updating the whitelist; filtering on reserved/top-level fields.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Not allowed filter identifier name:
• Not supported expression type:
• The 'IN' operator should have been transformed into chain…
• The 'NIN' operator should have been transformed into chain…
• Unsupported value type:

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/ed67290e9b5ad392. Report an issue: GitHub.

Appendix: source

Thrown at vector-stores/spring-ai-weaviate-store/src/main/java/org/springframework/ai/vectorstore/weaviate/WeaviateFilterExpressionConverter.java:143

	@Override
	protected void doKey(Key key, StringBuilder context) {
		var identifier = (hasOuterQuotes(key.key())) ? removeOuterQuotes(key.key()) : key.key();
		context.append("path:[");
		emitJsonValue(withMetaPrefix(identifier), context);
		context.append("] \n");
	}

	public String withMetaPrefix(String identifier) {
		if (SYSTEM_IDENTIFIERS.contains(identifier)) {
			return identifier;
		}

		if (this.allowedIdentifierNames.contains(identifier)) {
			return this.metaFieldPrefix + identifier;
		}

		throw new IllegalArgumentException("Not allowed filter identifier name: " + identifier
				+ ". Consider adding it to WeaviateVectorStore#filterMetadataKeys.");
	}

	@Override
	protected void doValue(Filter.Value filterValue, StringBuilder context) {
		if (filterValue.value() instanceof List) {
			// nothing
			throw new IllegalStateException("");
		}
		else {
			this.doSingleValue(filterValue.value(), context);
		}
	}

	@Override
	protected void doSingleValue(Object value, StringBuilder context) {
		String singleValueFormat = "valueNumber:%s ";
		if (value instanceof Integer i) {

View on GitHub (pinned to 98a7beda4f)