spring-projects/spring-ai · error · IllegalArgumentException

Not allowed filter identifier name:

Error message

Not allowed filter identifier name: 

What it means

withMetaPrefix prefixes a filter identifier with 'meta_' so it maps to a metadata field in the Azure AI Search index, but only if the identifier appears in this converter's allowlist of permitted field names (allowedIdentifierNames). Any other identifier — typically a reserved Azure field like 'id' or a non-whitelisted metadata key — is rejected with an IllegalArgumentException.

Source

Thrown at vector-stores/spring-ai-azure-store/src/main/java/org/springframework/ai/vectorstore/azure/AzureAiSearchFilterExpressionConverter.java:119

		}
		context.append(prefixedIdentifier);
	}

	/**
	 * Adds the metadata field prefix to the given identifier name. Azure AI Search
	 * requires metadata fields to be prefixed with "meta_" to distinguish them from
	 * system fields.
	 * @param identifier the field identifier without prefix
	 * @return the prefixed field identifier (e.g., "meta_fieldName")
	 * @throws IllegalArgumentException if the identifier is not in the allowed list
	 */
	public String withMetaPrefix(String identifier) {

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

		throw new IllegalArgumentException("Not allowed filter identifier name: " + identifier);
	}

	@Override
	protected void doValue(Filter.Value filterValue, StringBuilder context) {
		if (filterValue.value() instanceof List list) {
			// search.in(field, 'val1,val2,val3', ',') requires one string literal
			doStartValueRange(filterValue, context);
			int c = 0;
			for (Object v : list) {
				appendListElementContent(normalizeDateString(v), context);
				if (c++ < list.size() - 1) {
					this.doAddValueRangeSpitter(filterValue, context);
				}
			}
			this.doEndValueRange(filterValue, context);
		}
		else {
			this.doSingleValue(normalizeDateString(filterValue.value()), context);

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Register the identifier in the converter/Builder allowlist (e.g. via metadataFields when building AzureAiSearchVectorStore) so it is in allowedIdentifierNames
2. Filter only on fields declared in the index's metadataFields configuration
3. If the field is a native Azure index column, avoid the metadata path — reference it without the meta_ prefix rather than via withMetaPrefix
4. Catch IllegalArgumentException around filter construction/conversion and log which identifier was rejected

Example fix

// before
AzureAiSearchVectorStore store = AzureAiSearchVectorStore.builder(client)
    .metadataFields(MetadataField.tag("category"))
    .build();
// filter on 'author' -> throws
// after
AzureAiSearchVectorStore store = AzureAiSearchVectorStore.builder(client)
    .metadataFields(MetadataField.tag("category"), MetadataField.tag("author"))
    .build(); // 'author' now passes withMetaPrefix -> meta_author

Set<String> allowed = /* metadata fields configured on the store */;
if (!allowed.contains(identifier)) { throw new IllegalArgumentException("Identifier not registered for Azure filtering: " + identifier); }

try { String filter = azureConverter.convertExpression(expression); ... } catch (IllegalArgumentException e) { log.error("Filter identifier rejected: {}", e.getMessage()); throw new InvalidRequestException(e); }

When it happens

Trigger: Building a filter expression that references an identifier not in the converter's allowedIdentifierNames, e.g. new ExpressionText("content") or ("id") inside a filter passed to AzureAiSearchVectorStore.similaritySearch, or calling converter.withMetaPrefix("myCustomField") directly when allowlist was configured without that name.

Common situations: Constructing a vector store with a Builder.metadataFields(...) allowlist but then filtering on a metadata key that was not registered; filtering on built-in Azure index fields (id, content, embedding) that must not be meta-prefixed; renaming a metadata key in documents without updating the allowlist.

Related errors

• Not supported expression type:
• Host '' is not in the allowed hosts list. Configure MediaFet
• Base URL must be provided for Microsoft Foundry.
• Microsoft Foundry was detected, but no credential was provid
• Unsupported operand type:

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