{"record":{"id":"099b05077fd60443","repo":"chroma-core/chroma","slug":"or-cannot-be-combined-with-other-keys","errorCode":null,"errorMessage":"$or cannot be combined with other keys","messagePattern":"\\$or cannot be combined with other keys","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/execution/expression/where.ts","lineNumber":187,"sourceCode":"      if (!expr) {\n        throw new TypeError(`Invalid where clause at index ${index}`);\n      }\n      return expr;\n    });\n    if (conditions.length === 1) {\n      return conditions[0];\n    }\n    return conditions\n      .slice(1)\n      .reduce(\n        (acc, condition) => AndWhere.combine(acc, condition),\n        conditions[0],\n      );\n  }\n\n  if (\"$or\" in data) {\n    if (Object.keys(data).length !== 1) {\n      throw new Error(\"$or cannot be combined with other keys\");\n    }\n    const rawConditions = data[\"$or\"];\n    if (!Array.isArray(rawConditions) || rawConditions.length === 0) {\n      throw new TypeError(\"$or must be a non-empty array\");\n    }\n    const conditions = rawConditions.map((item, index) => {\n      const expr = WhereExpression.from(item as WhereInput);\n      if (!expr) {\n        throw new TypeError(`Invalid where clause at index ${index}`);\n      }\n      return expr;\n    });\n    if (conditions.length === 1) {\n      return conditions[0];\n    }\n    return conditions\n      .slice(1)\n      .reduce(","sourceCodeStart":169,"sourceCodeEnd":205,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/execution/expression/where.ts#L169-L205","documentation":"Thrown by parseWhereDict (where.ts:187) when a where dict contains an $or key alongside any other key. Exactly like $and, the $or combinator must be the only key in its object; its value must be a non-empty array of clauses. Any sibling key — another condition or even $and — produces this plain Error client-side.","triggerScenarios":"Passing { $or: [{ a: 1 }, { b: 2 }], limit: { $lt: 10 } } — the sibling must move inside the $or array; also { $or: [...], $and: [...] } in a single object, which must be split into nested clauses.","commonSituations":"Adding 'any of these tags' ($or) on top of an existing dict without restructuring; merging filter fragments with object spread where one side already contains $or; translating (a OR b) AND c directly into a mixed dict instead of { $and: [{ $or: [a, b] }, c] }.","solutions":["Move sibling conditions into the $or array: { $or: [condA, condB, { limit: { $lt: 10 } }] }","For mixed AND/OR logic, nest: { $and: [{ $or: [a, b] }, c] }","Or compose programmatically with WhereExpression .or()/.and() to avoid manual nesting"],"exampleFix":"// before\nconst where = { $or: [{ a: 1 }, { b: 2 }], channel: { $eq: 'email' } };\n\n// after\nconst where = {\n  $and: [{ $or: [{ a: 1 }, { b: 2 }] }, { channel: { $eq: 'email' } }],\n};","handlingStrategy":"validation","validationCode":"const combineOr = (clauses: Record<string, unknown>[]): Record<string, unknown> =>\n  clauses.length > 1 ? { $or: clauses } : clauses[0];\n// any AND over an $or must be nested: { $and: [{ $or: [...] }, other] }","typeGuard":null,"tryCatchPattern":"try {\n  const results = await collection.query({ where });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('$or cannot be combined')) {\n    const { $or, ...rest } = where;\n    const key = Object.keys(rest)[0];\n    return collection.query({\n      where: { $and: [{ $or: $or as object[] }, { [key]: rest[key] }] },\n    });\n  }\n  throw e;\n}","preventionTips":["$or must be the sole key of its object — nest it under $and to combine with other conditions","Use WhereExpression .or()/.and() so nesting is generated for you","Do not object-spread fragments that already contain $or"],"tags":["where","or","query-filter","input-validation"],"backgroundTag":"invalid-query-filter","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}