deepset-ai/haystack · error · FilterError

Unknown logical operator '{operator}'. Valid operators are:

Error message

Unknown logical operator '{operator}'. Valid operators are: {sorted(LOGICAL_OPERATORS)}

What it means

The 'operator' in a logical condition must be one of LOGICAL_OPERATORS (AND/OR, case-sensitive as registered). Any other string raises this FilterError listing the valid operators.

Source

Thrown at haystack/utils/filters.py:279

    "<=": _less_than_equal,
    "in": _in,
    "not in": _not_in,
}


def _logic_condition(
    condition: dict[str, Any], document: Document | ByteStream, strict_datetime_comparison: bool
) -> bool:
    if "operator" not in condition:
        msg = f"'operator' key missing in {condition}"
        raise FilterError(msg)
    if "conditions" not in condition:
        msg = f"'conditions' key missing in {condition}"
        raise FilterError(msg)
    operator: str = condition["operator"]
    if operator not in LOGICAL_OPERATORS:
        msg = f"Unknown logical operator '{operator}'. Valid operators are: {sorted(LOGICAL_OPERATORS)}"
        raise FilterError(msg)
    conditions: list[dict[str, Any]] = condition["conditions"]
    return LOGICAL_OPERATORS[operator](
        document=document, conditions=conditions, strict_datetime_comparison=strict_datetime_comparison
    )


def _comparison_condition(
    condition: dict[str, Any], document: Document | ByteStream, strict_datetime_comparison: bool
) -> bool:
    if "field" not in condition:
        # 'field' key is only found in comparison dictionaries.
        # We assume this is a logic dictionary since it's not present.
        return _logic_condition(
            condition=condition, document=document, strict_datetime_comparison=strict_datetime_comparison
        )
    field: str = condition["field"]

    if "operator" not in condition:

View on GitHub (pinned to e318778c9b)

Solutions

Use a supported logical operator exactly as listed in the error message (e.g. "AND" or "OR").
Don't express negation with a logical operator; use 'not in'/'!=' comparison operators instead.
Validate operator strings against haystack.utils.filters.LOGICAL_OPERATORS before applying.

Example fix

// before
filters = {"operator": "and", "conditions": [...]}
// after
filters = {"operator": "AND", "conditions": [...]}

Defensive patterns

Strategy: validation

Validate before calling

from haystack.utils.filters import LOGICAL_OPERATORS
assert condition.get("operator") in LOGICAL_OPERATORS, condition["operator"]

Type guard

def is_valid_logical_op(c: dict) -> bool:
    return c.get("operator") in LOGICAL_OPERATORS

Try / catch

try:
    ok = document_matches_filter(doc, filters)
except FilterError as e:
    logger.warning("bad logical operator: %s", e)
    ok = False

Prevention

Use exact registered logical operators ('AND'/'OR').
Check LOGICAL_OPERATORS when unsure of valid values.
Beware lowercasing pipelines that mangle operator strings.

When it happens

Trigger: Passing {"operator": "and", ...} if only uppercase is accepted, or values like 'NOT', '&&', or 'xor' in a logical condition.

Common situations: Lowercasing filter keys programmatically; translating SQL/boolean expressions into Haystack filters; using comparison operator strings ('==') at the logical level.

Related errors

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