{"record":{"id":"8b7b105f89985848","repo":"chroma-core/chroma","slug":"div-requires-left-and-right-fields","errorCode":null,"errorMessage":"$div requires 'left' and 'right' fields","messagePattern":"\\$div requires 'left' and 'right' fields","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/execution/expression/operator.py","lineNumber":805,"sourceCode":"            if len(ranks_data) < 2:\n                raise ValueError(\n                    f\"$mul requires at least 2 ranks, got {len(ranks_data)}\"\n                )\n\n            ranks = [Rank.from_dict(r) for r in ranks_data]\n            result = ranks[0]\n            for r in ranks[1:]:\n                result = result * r\n            return result\n\n        elif op == \"$div\":\n            div_data = data[\"$div\"]\n            if not isinstance(div_data, dict):\n                raise TypeError(\n                    f\"$div requires a dict with 'left' and 'right', got {type(div_data).__name__}\"\n                )\n            if \"left\" not in div_data or \"right\" not in div_data:\n                raise ValueError(\"$div requires 'left' and 'right' fields\")\n\n            left = Rank.from_dict(div_data[\"left\"])\n            right = Rank.from_dict(div_data[\"right\"])\n            return left / right\n\n        elif op == \"$abs\":\n            child_data = data[\"$abs\"]\n            if not isinstance(child_data, dict):\n                raise TypeError(\n                    f\"$abs requires a rank dict, got {type(child_data).__name__}\"\n                )\n            return abs(Rank.from_dict(child_data))\n\n        elif op == \"$exp\":\n            child_data = data[\"$exp\"]\n            if not isinstance(child_data, dict):\n                raise TypeError(\n                    f\"$exp requires a rank dict, got {type(child_data).__name__}\"","sourceCodeStart":787,"sourceCodeEnd":823,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/execution/expression/operator.py#L787-L823","documentation":"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.","triggerScenarios":"Rank.from_dict({'$div': {'left': knn}}) with 'right' missing, or keys renamed ('numerator'/'denominator', 'a'/'b') by a generator or hand-edited JSON.","commonSituations":"Dynamically built dicts that omit the denominator when it is None; abbreviation of key names; partially copied example expressions.","solutions":["Include both keys: {\"$div\": {\"left\": <rank>, \"right\": <rank or $val>}}","For 'divide by nothing' cases use {\"$val\": 1} as the right operand instead of omitting the key","Assert 'left' in payload and 'right' in payload before deserialization","Generate the expression via Python division and .to_dict()"],"exampleFix":"# before\nexpr = {\"$div\": {\"left\": knn_rank}}\n\n# after\nexpr = {\"$div\": {\"left\": knn_rank, \"right\": {\"$val\": 10.0}}}","handlingStrategy":"validation","validationCode":"div = rank_expr.get(\"$div\")\nif not (isinstance(div, dict) and \"left\" in div and \"right\" in div):\n    raise ValueError(f\"$div requires 'left' and 'right': {rank_expr!r}\")","typeGuard":"def is_complete_div_expr(d) -> bool:\n    return (isinstance(d, dict) and set(d) == {\"$div\"}\n            and isinstance(d[\"$div\"], dict)\n            and {\"left\", \"right\"} <= set(d[\"$div\"]))","tryCatchPattern":"try:\n    rank = Rank.from_dict(rank_expr)\nexcept (TypeError, ValueError) as e:\n    raise ValueError(f\"invalid rank expression {rank_expr!r}: {e}\") from e","preventionTips":["Always include both numerator ('left') and denominator ('right')","Use {\"$val\": 1} as an identity denominator when the right side is optional in your logic","Let the library emit the shape via Python division and .to_dict()"],"tags":["chromadb","rank-expression","validation","deserialization","missing-field"],"backgroundTag":"query-expression-validation","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}