deepset-ai/haystack · error · FilterError

Unknown comparison operator '{operator}'. Valid operators ar

Error message

Unknown comparison operator '{operator}'. Valid operators are: {sorted(COMPARISON_OPERATORS)}

What it means

FilterError raised by `_comparison_condition` when the condition's 'operator' string is not one of the registered COMPARISON_OPERATORS (e.g. ==, !=, >, >=, <, <=, in, not in). The operator lookup dict is only populated with supported comparison functions, so an unknown string cannot be dispatched.

Source

Thrown at haystack/utils/filters.py:329

                # If a field is not found (or an intermediate value is not a dict,
                # e.g. None) we treat it as None
                document_value = None
                break
            document_value = document_value[part]
    elif field not in [f.name for f in fields(document)]:
        # Converted legacy filters don't add the `meta.` prefix, so we assume
        # that all filter fields that are not actual fields in Document are converted
        # filters.
        #
        # We handle this to avoid breaking compatibility with converted legacy filters.
        # This will be removed as soon as we stop supporting legacy filters.
        document_value = document.meta.get(field)
    else:
        document_value = getattr(document, field)
    operator: str = condition["operator"]
    if operator not in COMPARISON_OPERATORS:
        msg = f"Unknown comparison operator '{operator}'. Valid operators are: {sorted(COMPARISON_OPERATORS)}"
        raise FilterError(msg)
    filter_value: Any = condition["value"]
    return COMPARISON_OPERATORS[operator](
        filter_value=filter_value, value=document_value, strict_datetime_comparison=strict_datetime_comparison
    )

View on GitHub (pinned to e318778c9b)

Solutions

1. Use a valid operator from COMPARISON_OPERATORS (==, !=, >, >=, <, <=, in, not in as registered)
2. Print haystack.utils.filters.COMPARISON_OPERATORS.keys() to see exactly which operators your version supports
3. Check for typos and case-sensitivity in the operator string

Example fix

// before
filters = {"field": "meta.price", "operator": "gt", "value": 10}
// after
filters = {"field": "meta.price", "operator": ">", "value": 10}

from haystack.utils.filters import COMPARISON_OPERATORS
def validate_operator(cond):
    if cond.get("operator") not in COMPARISON_OPERATORS:
        raise ValueError(f"operator must be one of {sorted(COMPARISON_OPERATORS)}")

def has_known_operator(c) -> bool:
    from haystack.utils.filters import COMPARISON_OPERATORS
    return isinstance(c, dict) and c.get("operator") in COMPARISON_OPERATORS

from haystack.utils import FilterError
try:
    result = document_matches_filter(doc, condition)
except FilterError as e:
    raise ValueError(f"Unsupported filter: {e}") from e

When it happens

Trigger: Passing a condition like {'field': 'meta.price', 'operator': 'equals', 'value': 10} or '==' misspellings / unsupported operators such as '~=', 'contains' (if not registered), 'like', or 'gt' to document_matches_filter, _and, _or, or any component that applies filters.

Common situations: Typo in the operator string; using natural-language operator names instead of the symbols Haystack expects; copying filter syntax from another library (e.g. Elasticsearch 'term'/'match' or pandas style); code that predates an operator being added.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• 'value' key missing in {condition}
• Filter value can't be of type {type(filter_value)} using ope
• Can't compare strings using operators '>', '>=', '<', '<='.
• Filter value must be a `list` when using operator 'in' or 'n
• 'operator' key missing in {condition}

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/7ddc1ae92e664db4. Report an issue: GitHub.