{"record":{"id":"a5f122234bf18bed","repo":"chroma-core/chroma","slug":"expected-operand-for-operator-to-be-a-list-of","errorCode":null,"errorMessage":"Expected operand for ${operator} to be a list of 'whereDocument' expressions, but got ${operand}","messagePattern":"Expected operand for (.+?) to be a list of 'whereDocument' expressions, but got (.+?)","errorType":"validation","errorClass":"ChromaValueError","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/utils.ts","lineNumber":682,"sourceCode":"    ![\n      \"$contains\",\n      \"$not_contains\",\n      \"$matches\",\n      \"$not_matches\",\n      \"$regex\",\n      \"$not_regex\",\n      \"$and\",\n      \"$or\",\n    ].includes(operator)\n  ) {\n    throw new ChromaValueError(\n      `Expected 'whereDocument' operator to be one of $contains, $not_contains, $matches, $not_matches, $regex, $not_regex, $and, or $or, but got ${operator}`,\n    );\n  }\n\n  if (operator === \"$and\" || operator === \"$or\") {\n    if (!Array.isArray(operand)) {\n      throw new ChromaValueError(\n        `Expected operand for ${operator} to be a list of 'whereDocument' expressions, but got ${operand}`,\n      );\n    }\n\n    if (operand.length <= 1) {\n      throw new ChromaValueError(\n        `Expected 'whereDocument' operand for ${operator} to be a list with at least two 'whereDocument' expressions`,\n      );\n    }\n\n    operand.forEach((item) => validateWhereDocument(item));\n  }\n\n  if (\n    (operand === \"$contains\" ||\n      operand === \"$not_contains\" ||\n      operand === \"$regex\" ||\n      operand === \"$not_regex\") &&","sourceCodeStart":664,"sourceCodeEnd":700,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/utils.ts#L664-L700","documentation":"When the single top-level operator is $and or $or, its operand must be an array of whereDocument expressions (utils.ts:680-685). Passing an object, a string, or any non-array throws this ChromaValueError from validateWhereDocument before a request is sent. Each array element is subsequently validated recursively by the same function.","triggerScenarios":"collection.query({ queryTexts: [...], whereDocument: { $and: { $contains: 'a' } } }) (nested object instead of array); { $or: 'text' }; { $and: 123 }.","commonSituations":"Assuming Mongo-style nested-object conjunctions; adding a second condition and wrapping clauses in braces instead of brackets.","solutions":["Wrap the sub-clauses in an array: { $and: [{ $contains: 'a' }, { $not_contains: 'b' }] }","Make sure every array element is itself a valid single-operator whereDocument object","Rely on the WhereDocument type — { $and: WhereDocument[] } is enforced by the compiler"],"exampleFix":"// before\nwhereDocument: { $and: { $contains: 'a' } }\n\n// after\nwhereDocument: { $and: [{ $contains: 'a' }, { $not_contains: 'b' }] }","handlingStrategy":"validation","validationCode":"function isCompoundWhereDocument(w: Record<string, unknown>): boolean {\n  const [op, val] = Object.entries(w)[0];\n  if (op !== '$and' && op !== '$or') return true; // not compound, nothing to check here\n  return Array.isArray(val);\n}\nif (whereDocument && !isCompoundWhereDocument(whereDocument)) {\n  throw new TypeError('$and/$or require an array of whereDocument clauses');\n}","typeGuard":"const isCompoundClause = (w: unknown): w is { $and: unknown[] } | { $or: unknown[] } =>\n  typeof w === 'object' && w !== null &&\n  (('$and' in w) || ('$or' in w)) && Array.isArray((w as Record<string, unknown>).$and ?? (w as Record<string, unknown>).$or);","tryCatchPattern":"try {\n  await col.query({ queryTexts, whereDocument: { $and: clauses } });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('list of')) {\n    clauses = [clauses].flat(2); // normalize accidental object/scalar into an array and retry\n  } else throw e;\n}","preventionTips":["Always build $and/$or operands as arrays: { $and: [ ...clauses ] }","Add a builder helper (and(clauses) / or(clauses)) that enforces the array shape","Let the WhereDocument union type reject object-style conjunctions at compile time"],"tags":["javascript","typescript","validation","where-document","logical-operators"],"backgroundTag":"invalid-query-filter","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}