{"record":{"id":"88702006d1896633","repo":"chroma-core/chroma","slug":"knn-key-must-be-a-string-or-key-instance","errorCode":null,"errorMessage":"Knn key must be a string or Key instance","messagePattern":"Knn key must be a string or Key instance","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/execution/expression/rank.ts","lineNumber":410,"sourceCode":"    query = queryInput;\n  } else if (\n    isPlainObject(queryInput) &&\n    Array.isArray((queryInput as SparseVector).indices) &&\n    Array.isArray((queryInput as SparseVector).values)\n  ) {\n    const sparse = queryInput as SparseVector;\n    query = {\n      indices: sparse.indices.slice(),\n      values: sparse.values.slice(),\n    };\n  } else {\n    query = normalizeDenseVector(queryInput as IterableInput<number>);\n  }\n\n  const key =\n    options.key instanceof Key ? options.key.name : options.key ?? \"#embedding\";\n  if (typeof key !== \"string\") {\n    throw new TypeError(\"Knn key must be a string or Key instance\");\n  }\n\n  const defaultValue =\n    options.default === null || options.default === undefined\n      ? undefined\n      : requireNumber(options.default, \"Knn default must be a number\");\n\n  if (defaultValue !== undefined && !Number.isFinite(defaultValue)) {\n    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,","sourceCodeStart":392,"sourceCodeEnd":428,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/execution/expression/rank.ts#L392-L428","documentation":"Thrown by normalizeKnnOptions in the Chroma JS client (rank.ts:410) when Knn()'s `key` option is neither a string nor a Key instance. The key names the field to search (default '#embedding'); a Key instance is unwrapped to its .name. Note the fallback `options.key ?? '#embedding'` only substitutes for null/undefined — any other non-string value (0, false, {}, []) reaches the typeof check and throws.","triggerScenarios":"Calling Knn({ query, key: 0 }) or key: false (falsy but not nullish, so the ?? fallback does not apply); key: { name: 'emb' } or key: ['emb'] (plain object/array instead of Key/string); key computed from a lookup that returns a number or undefined-turned-wrong-type via type coercion.","commonSituations":"Mixing up metadata field names that are numeric IDs with Key objects; passing a Key-like object from another library version (e.g. after a package upgrade where Key is a different class instance); copying Python-client snippets where keys can be other types; storing keys in config as non-strings.","solutions":["Pass a string field name: Knn({ query, key: 'my_embedding' })","Or pass a Key instance built with the same library version: Knn({ query, key: K('my_embedding') }) or Key.EMBEDDING","If the key comes from dynamic data, normalize it first: typeof k === 'string' || k instanceof Key ? k : '#embedding'"],"exampleFix":"// before\nconst rank = Knn({ query: vec, key: 0 }); // throws: not nullish, not a string\n\n// after\nconst rank = Knn({ query: vec, key: K('my_embedding') });\n// or simply omit key to search '#embedding'","handlingStrategy":"type-guard","validationCode":"const normalizeKnnKey = (k: unknown): string | Key =>\n  k instanceof Key || typeof k === 'string' ? (k as string | Key) : '#embedding';\nconst rank = Knn({ query: vec, key: normalizeKnnKey(cfg.key) });","typeGuard":"const isKeyLike = (v: unknown): v is string | Key =>\n  v == null || typeof v === 'string' || v instanceof Key;","tryCatchPattern":"try {\n  const rank = Knn({ query: vec, key });\n} catch (e) {\n  if (e instanceof TypeError && e.message.includes('Knn key')) {\n    return Knn({ query: vec, key: K('my_embedding') });\n  }\n  throw e;\n}","preventionTips":["Use K('field') or the Key constants so types are guaranteed","Remember `??` only covers null/undefined: key: 0 or key: false still throw","Keep a single copy of the chromadb package — instanceof Key fails across duplicated versions"],"tags":["knn","key","input-validation","type-error","client-side"],"backgroundTag":"invalid-argument-type","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}