{"record":{"id":"6c27f9bc436e9ae5","repo":"run-llama/llama_index","slug":"invalid-operator-operator","errorCode":null,"errorMessage":"Invalid operator: {operator}","messagePattern":"Invalid operator: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/vector_stores/utils.py","lineNumber":157,"sourceCode":"                if isinstance(value, str) and isinstance(metadata_value, str):\n                    return value in metadata_value\n                raise TypeError(\n                    \"Both metadata_value and value should be strings to be used with a \"\n                    \"TEXT_MATCH filter\"\n                )\n            if operator == FilterOperator.TEXT_MATCH_INSENSITIVE:\n                if isinstance(value, str) and isinstance(metadata_value, str):\n                    return value.lower() in metadata_value.lower()\n                raise TypeError(\n                    \"Both metadata_value and value should be strings to be used with a \"\n                    \"TEXT_MATCH_INSENSITIVE filter\"\n                )\n            if operator == FilterOperator.ALL:\n                return all(val in metadata_value for val in value)\n            if operator == FilterOperator.ANY:\n                return any(val in metadata_value for val in value)\n\n            raise ValueError(f\"Invalid operator: {operator}\")\n\n        metadata = metadata_lookup_fn(node_id)\n\n        filter_matches_list = []\n        for filter_ in filter_list:\n            if isinstance(filter_, MetadataFilters):\n                raise ValueError(\"Nested MetadataFilters are not supported.\")\n\n            filter_matches = True\n            metadata_value = metadata.get(filter_.key, None)\n            if filter_.operator == FilterOperator.IS_EMPTY:\n                filter_matches = (\n                    metadata_value is None\n                    or metadata_value == \"\"\n                    or metadata_value == []\n                )\n            else:\n                filter_matches = _process_filter_match(","sourceCodeStart":139,"sourceCodeEnd":175,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/vector_stores/utils.py#L139-L175","documentation":"The tail of `_process_filter_match`'s operator dispatch: every FilterOperator member is compared explicitly, and anything not matched by the preceding chain falls through to `raise ValueError(f\"Invalid operator: {operator}\")`. In practice this is reached when a raw string (e.g. \"eq\") is passed where a FilterOperator enum was expected, so none of the `operator == FilterOperator.X` comparisons match. It also fires if a new operator enum value exists that this llama-index-core version predates.","triggerScenarios":"Constructing MetadataFilter with `operator=\"gte\"` (a bare string) instead of `FilterOperator.GTE`; mixing llama-index versions where an integration emits a newer FilterOperator member than the installed core understands; passing a custom enum or None as operator.","commonSituations":"Copy-pasting filter code that uses string literals; config-driven filter builders (YAML/JSON) that read operator names as strings without conversion; version skew between llama-index-core and a vector-store integration pack.","solutions":["Always use the enum: `from llama_index.core.vector_stores import FilterOperator` and pass `FilterOperator.GTE` etc.","Convert strings via `FilterOperator(value_str)` with try/except for config-driven inputs.","Align versions: upgrade llama-index-core (and integration packs) together so operator enums match.","Validate operators against `list(FilterOperator)` before building filters."],"exampleFix":"# before\nf = MetadataFilter(key=\"year\", value=2020, operator=\"gte\")  # falls through\n\n# after\nfrom llama_index.core.vector_stores import FilterOperator\nf = MetadataFilter(key=\"year\", value=2020, operator=FilterOperator.GTE)","handlingStrategy":"type-guard","validationCode":"from llama_index.core.vector_stores import FilterOperator\n\ndef coerce_operator(op):\n    if isinstance(op, FilterOperator):\n        return op\n    try:\n        return FilterOperator(op)\n    except ValueError:\n        raise ValueError(f\"unknown filter operator: {op!r}; valid: {[m.value for m in FilterOperator]}\")","typeGuard":"def is_valid_operator(op) -> bool:\n    from llama_index.core.vector_stores import FilterOperator\n    return isinstance(op, FilterOperator) and op in list(FilterOperator)","tryCatchPattern":"try:\n    result = store.query(query)\nexcept ValueError as e:\n    if \"Invalid operator\" in str(e):\n        raise ValueError(\"pass FilterOperator enum members, not strings\") from e\n    raise","preventionTips":["Always construct filters with FilterOperator enum members.","Convert config strings via FilterOperator(value) with explicit error handling.","Keep llama-index-core and integration packages version-aligned to avoid enum drift."],"tags":["metadata-filters","enum","operator","version-skew","python"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}