{"record":{"id":"9981aa28a0a140d5","repo":"chroma-core/chroma","slug":"max-requires-a-list-got-type-ranks-data-name","errorCode":null,"errorMessage":"$max requires a list, got {type(ranks_data).__name__}","messagePattern":"\\$max requires a list, got (.+?)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"chromadb/execution/expression/operator.py","lineNumber":838,"sourceCode":"            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__}\"\n                )\n            return Rank.from_dict(child_data).exp()\n\n        elif op == \"$log\":\n            child_data = data[\"$log\"]\n            if not isinstance(child_data, dict):\n                raise TypeError(\n                    f\"$log requires a rank dict, got {type(child_data).__name__}\"\n                )\n            return Rank.from_dict(child_data).log()\n\n        elif op == \"$max\":\n            ranks_data = data[\"$max\"]\n            if not isinstance(ranks_data, (list, tuple)):\n                raise TypeError(\n                    f\"$max requires a list, got {type(ranks_data).__name__}\"\n                )\n            if len(ranks_data) < 2:\n                raise ValueError(\n                    f\"$max 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.max(r)\n            return result\n\n        elif op == \"$min\":\n            ranks_data = data[\"$min\"]\n            if not isinstance(ranks_data, (list, tuple)):\n                raise TypeError(\n                    f\"$min requires a list, got {type(ranks_data).__name__}\"","sourceCodeStart":820,"sourceCodeEnd":856,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/execution/expression/operator.py#L820-L856","documentation":"$max folds a chain of pairwise maximums over rank expressions (used e.g. for clamping scores) and, like $sum/$mul, expects its payload to be a list of operand dicts. Rank.from_dict raises this TypeError when the $max payload is not a list/tuple — commonly a {'left','right'} dict copied from the $sub/$div style.","triggerScenarios":"Rank.from_dict({'$max': {'left': a, 'right': b}}) or {'$max': 1.0} at any depth of a rank expression tree.","commonSituations":"Clamping expressions (score.max(1.0)) written by hand where the author alternates between the two payload conventions; generic expression builders emitting the dict shape for all binary operators.","solutions":["Use the list form: {\"$max\": [rank_a, {\"$val\": 1.0}]}","Convert pair dicts: {'$max': [pair['left'], pair['right']]}","Build in Python as rank.max(1.0).to_dict()","Guard: isinstance(expr['$max'], (list, tuple)) before deserialization"],"exampleFix":"# before\nexpr = {\"$max\": {\"left\": knn_rank, \"right\": {\"$val\": 1.0}}}\n\n# after\nexpr = {\"$max\": [knn_rank, {\"$val\": 1.0}]}","handlingStrategy":"validation","validationCode":"def valid_max_expr(expr):\n    return (\n        isinstance(expr, dict) and set(expr) == {\"$max\"}\n        and isinstance(expr[\"$max\"], (list, tuple))\n    )\n\nif not valid_max_expr(rank_expr):\n    raise ValueError(f\"$max payload must be a list: {rank_expr!r}\")","typeGuard":"def is_max_expr(d) -> bool:\n    return (isinstance(d, dict) and set(d) == {\"$max\"}\n            and isinstance(d[\"$max\"], (list, tuple)))","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":["$max/$min use the list convention like $sum/$mul, unlike $sub/$div","Emit clamps from Python: rank.max(1.0).to_dict()","Schema-test all operator payload shapes your code can generate"],"tags":["chromadb","rank-expression","validation","deserialization","type-error"],"backgroundTag":"query-expression-validation","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}