{"record":{"id":"dbdc4b5bf0b10428","repo":"chroma-core/chroma","slug":"context-must-be-a-rank-expression","errorCode":null,"errorMessage":"${context} must be a rank expression","messagePattern":"(.+?) must be a rank expression","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/execution/expression/rank.ts","lineNumber":437,"sourceCode":"    throw new TypeError(\"Knn default must be a finite number\");\n  }\n\n  return {\n    query:\n      Array.isArray(query) || typeof query === \"string\"\n        ? query\n        : deepClone(query),\n    key,\n    limit,\n    defaultValue,\n    returnRank: options.returnRank ?? false,\n  };\n};\n\nconst requireRank = (input: RankInput, context: string): RankExpression => {\n  const result = RankExpression.from(input);\n  if (!result) {\n    throw new TypeError(`${context} must be a rank expression`);\n  }\n  return result;\n};\n\nexport const Val = (value: number): RankExpression =>\n  new ValueRankExpression(requireNumber(value, \"Val requires a numeric value\"));\n\nexport const Knn = (options: KnnOptions): RankExpression =>\n  new KnnRankExpression(normalizeKnnOptions(options));\n\nexport interface RrfOptions {\n  ranks: RankInput[];\n  k?: number;\n  weights?: number[];\n  normalize?: boolean;\n}\n\nexport const Rrf = ({","sourceCodeStart":419,"sourceCodeEnd":455,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/execution/expression/rank.ts#L419-L455","documentation":"Thrown by requireRank (rank.ts:437) when a value in a rank-operand position fails to convert via RankExpression.from. Because from() accepts RankExpression instances, plain numbers, and plain objects — and throws its own distinct TypeError for other types — this message fires specifically when the operand is null or undefined. The ${context} prefix names the exact slot: 'Sub left', 'Div right', 'Sum operand 0', 'ranks[1]', 'add operand 0', 'Abs', 'Exp', 'Log', etc.","triggerScenarios":"Sub(null, Val(1)); expr.add(undefined); Mul(Val(2), null); Rrf({ ranks: [Val(1), null] }); Abs(undefined). Most common real shape: building operands from an array containing optional/missing entries — Sum(...parts) where parts includes null or undefined.","commonSituations":"Conditionally assembled rank expressions where one branch produced undefined (e.g. an if without else); map lookups (dictionary.get(key)) returning undefined; API responses where a scoring component is absent; TypeScript any-typed pipelines that defeat compile-time checks.","solutions":["Find the slot named in the message (e.g. 'Sub left' = first argument of Sub) and ensure it is a RankExpression, number, or plain-object literal","Filter null/undefined out of operand arrays before spreading: parts.filter(p => p !== null && p !== undefined)","Give optional components an explicit numeric default: maybeRank ?? 0"],"exampleFix":"// before\nconst rank = Sum(...components); // components may contain undefined\n\n// after\nconst rank = Sum(\n  ...components.filter((p): p is Exclude<typeof p, null | undefined> => p != null),\n);","handlingStrategy":"validation","validationCode":"const compact = (parts: RankInput[]): RankInput[] =>\n  parts.filter((p): p is Exclude<RankInput, null | undefined> => p != null);\nif (compact(parts).length === 0) throw new Error('no rank components');\nconst rank = Sum(...compact(parts));","typeGuard":"const isNonNullRankInput = (v: unknown): v is RankInput =>\n  v instanceof RankExpression || typeof v === 'number' || typeof v === 'object';","tryCatchPattern":"try {\n  const rank = Sub(left, right);\n} catch (e) {\n  if (e instanceof TypeError && e.message.includes('must be a rank expression')) {\n    // message names the slot, e.g. 'Sub left' — fix that exact operand\n    throw new Error(`bad rank operand: ${e.message}`);\n  }\n  throw e;\n}","preventionTips":["Filter null/undefined from operand arrays before spreading","Do not use .filter(Boolean) blindly — it also drops 0, which is a valid numeric rank literal","Give optional components a default: maybeRank ?? 0"],"tags":["rank-expression","null-operand","undefined-operand","input-validation"],"backgroundTag":"null-argument","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}