{"record":{"id":"ed67290e9b5ad392","repo":"spring-projects/spring-ai","slug":"not-allowed-filter-identifier-name-consider-add","errorCode":null,"errorMessage":"Not allowed filter identifier name: . Consider adding it to WeaviateVectorStore#filterMetadataKeys.","messagePattern":"Not allowed filter identifier name: \\. Consider adding it to WeaviateVectorStore#filterMetadataKeys\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"vector-stores/spring-ai-weaviate-store/src/main/java/org/springframework/ai/vectorstore/weaviate/WeaviateFilterExpressionConverter.java","lineNumber":143,"sourceCode":"\n\t@Override\n\tprotected void doKey(Key key, StringBuilder context) {\n\t\tvar identifier = (hasOuterQuotes(key.key())) ? removeOuterQuotes(key.key()) : key.key();\n\t\tcontext.append(\"path:[\");\n\t\temitJsonValue(withMetaPrefix(identifier), context);\n\t\tcontext.append(\"] \\n\");\n\t}\n\n\tpublic String withMetaPrefix(String identifier) {\n\t\tif (SYSTEM_IDENTIFIERS.contains(identifier)) {\n\t\t\treturn identifier;\n\t\t}\n\n\t\tif (this.allowedIdentifierNames.contains(identifier)) {\n\t\t\treturn this.metaFieldPrefix + identifier;\n\t\t}\n\n\t\tthrow new IllegalArgumentException(\"Not allowed filter identifier name: \" + identifier\n\t\t\t\t+ \". Consider adding it to WeaviateVectorStore#filterMetadataKeys.\");\n\t}\n\n\t@Override\n\tprotected void doValue(Filter.Value filterValue, StringBuilder context) {\n\t\tif (filterValue.value() instanceof List) {\n\t\t\t// nothing\n\t\t\tthrow new IllegalStateException(\"\");\n\t\t}\n\t\telse {\n\t\t\tthis.doSingleValue(filterValue.value(), context);\n\t\t}\n\t}\n\n\t@Override\n\tprotected void doSingleValue(Object value, StringBuilder context) {\n\t\tString singleValueFormat = \"valueNumber:%s \";\n\t\tif (value instanceof Integer i) {","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/vector-stores/spring-ai-weaviate-store/src/main/java/org/springframework/ai/vectorstore/weaviate/WeaviateFilterExpressionConverter.java#L125-L161","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Add the field to filterMetadataKeys when building the store: WeaviateVectorStore.builder(...).filterMetadataKeys(List.of(\"category\"))...","Check for typos/case mismatches between the filter key and the registered whitelist entry.","If the field genuinely shouldn't be filtered, rewrite the query to filter on a registered field."],"exampleFix":"// before\nWeaviateVectorStore store = WeaviateVectorStore.builder(weaviateClient).build();\n// after\nWeaviateVectorStore store = WeaviateVectorStore.builder(weaviateClient)\n    .filterMetadataKeys(List.of(\"category\", \"author\"))\n    .build();","handlingStrategy":"validation","validationCode":"if (!registeredFilterMetadataKeys.contains(metadataKey)) throw new IllegalArgumentException(metadataKey + \" not in filterMetadataKeys\");","typeGuard":null,"tryCatchPattern":"try { vectorStore.similaritySearch(req); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"filterMetadataKeys\")) { /* add key to whitelist and rebuild store */ } else throw e; }","preventionTips":["List every filterable metadata field via WeaviateVectorStore.builder().filterMetadataKeys(...)","Keep the whitelist in sync with document metadata schemas","Validate user-supplied filter fields against the whitelist before querying"],"tags":["vector-store","weaviate","filter-expression","whitelist","identifier-validation"],"backgroundTag":"invalid-identifier-format","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}