chroma-core/chroma · error · ValueError

$div requires 'left' and 'right' fields

Error message

$div requires 'left' and 'right' fields

What it means

Chroma's $div operator requires the two field names 'left' (numerator) and 'right' (denominator) in its payload dict. Rank.from_dict raises this ValueError when the payload is a dict but either key is absent, meaning the division is underspecified.

Source

Thrown at chromadb/execution/expression/operator.py:805

            if len(ranks_data) < 2:
                raise ValueError(
                    f"$mul requires at least 2 ranks, got {len(ranks_data)}"
                )

            ranks = [Rank.from_dict(r) for r in ranks_data]
            result = ranks[0]
            for r in ranks[1:]:
                result = result * r
            return result

        elif op == "$div":
            div_data = data["$div"]
            if not isinstance(div_data, dict):
                raise TypeError(
                    f"$div requires a dict with 'left' and 'right', got {type(div_data).__name__}"
                )
            if "left" not in div_data or "right" not in div_data:
                raise ValueError("$div requires 'left' and 'right' fields")

            left = Rank.from_dict(div_data["left"])
            right = Rank.from_dict(div_data["right"])
            return left / right

        elif op == "$abs":
            child_data = data["$abs"]
            if not isinstance(child_data, dict):
                raise TypeError(
                    f"$abs requires a rank dict, got {type(child_data).__name__}"
                )
            return abs(Rank.from_dict(child_data))

        elif op == "$exp":
            child_data = data["$exp"]
            if not isinstance(child_data, dict):
                raise TypeError(
                    f"$exp requires a rank dict, got {type(child_data).__name__}"

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Include both keys: {"$div": {"left": <rank>, "right": <rank or $val>}}
2. For 'divide by nothing' cases use {"$val": 1} as the right operand instead of omitting the key
3. Assert 'left' in payload and 'right' in payload before deserialization
4. Generate the expression via Python division and .to_dict()

Example fix

# before
expr = {"$div": {"left": knn_rank}}

# after
expr = {"$div": {"left": knn_rank, "right": {"$val": 10.0}}}

div = rank_expr.get("$div")
if not (isinstance(div, dict) and "left" in div and "right" in div):
    raise ValueError(f"$div requires 'left' and 'right': {rank_expr!r}")

def is_complete_div_expr(d) -> bool:
    return (isinstance(d, dict) and set(d) == {"$div"}
            and isinstance(d["$div"], dict)
            and {"left", "right"} <= set(d["$div"]))

try:
    rank = Rank.from_dict(rank_expr)
except (TypeError, ValueError) as e:
    raise ValueError(f"invalid rank expression {rank_expr!r}: {e}") from e

When it happens

Trigger: Rank.from_dict({'$div': {'left': knn}}) with 'right' missing, or keys renamed ('numerator'/'denominator', 'a'/'b') by a generator or hand-edited JSON.

Common situations: Dynamically built dicts that omit the denominator when it is None; abbreviation of key names; partially copied example expressions.

Related errors

• $sub requires 'left' and 'right' fields
• $sum requires at least 2 ranks, got {len(ranks_data)}
• $sub requires a dict with 'left' and 'right', got {type(sub_
• $mul requires a list, got {type(ranks_data).__name__}
• $mul requires at least 2 ranks, got {len(ranks_data)}

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/8b7b105f89985848. Report an issue: GitHub.