chroma-core/chroma · error · Error

$or cannot be combined with other keys

Error message

$or cannot be combined with other keys

What it means

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.

Source

Thrown at clients/new-js/packages/chromadb/src/execution/expression/where.ts:187

      if (!expr) {
        throw new TypeError(`Invalid where clause at index ${index}`);
      }
      return expr;
    });
    if (conditions.length === 1) {
      return conditions[0];
    }
    return conditions
      .slice(1)
      .reduce(
        (acc, condition) => AndWhere.combine(acc, condition),
        conditions[0],
      );
  }

  if ("$or" in data) {
    if (Object.keys(data).length !== 1) {
      throw new Error("$or cannot be combined with other keys");
    }
    const rawConditions = data["$or"];
    if (!Array.isArray(rawConditions) || rawConditions.length === 0) {
      throw new TypeError("$or must be a non-empty array");
    }
    const conditions = rawConditions.map((item, index) => {
      const expr = WhereExpression.from(item as WhereInput);
      if (!expr) {
        throw new TypeError(`Invalid where clause at index ${index}`);
      }
      return expr;
    });
    if (conditions.length === 1) {
      return conditions[0];
    }
    return conditions
      .slice(1)
      .reduce(

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Move sibling conditions into the $or array: { $or: [condA, condB, { limit: { $lt: 10 } }] }
2. For mixed AND/OR logic, nest: { $and: [{ $or: [a, b] }, c] }
3. Or compose programmatically with WhereExpression .or()/.and() to avoid manual nesting

Example fix

// before
const where = { $or: [{ a: 1 }, { b: 2 }], channel: { $eq: 'email' } };

// after
const where = {
  $and: [{ $or: [{ a: 1 }, { b: 2 }] }, { channel: { $eq: 'email' } }],
};

const combineOr = (clauses: Record<string, unknown>[]): Record<string, unknown> =>
  clauses.length > 1 ? { $or: clauses } : clauses[0];
// any AND over an $or must be nested: { $and: [{ $or: [...] }, other] }

try {
  const results = await collection.query({ where });
} catch (e) {
  if (e instanceof Error && e.message.includes('$or cannot be combined')) {
    const { $or, ...rest } = where;
    const key = Object.keys(rest)[0];
    return collection.query({
      where: { $and: [{ $or: $or as object[] }, { [key]: rest[key] }] },
    });
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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] }.

Related errors

• $and cannot be combined with other keys
• $and must be a non-empty array
• Invalid where clause at index ${index}
• Where input must be a WhereExpression or plain object
• Expected document value for $and or $or to be a list with at

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/099b05077fd60443. Report an issue: GitHub.