chroma-core/chroma · error · TypeError

Invalid where clause at index ${index}

Error message

Invalid where clause at index ${index}

What it means

Thrown while parsing an $and (or $or) array (where.ts:170) when the clause at the reported index converts to undefined — which, given WhereExpression.from's rules, means the entry is null or undefined. Entries of other wrong types (strings, numbers, arrays) throw the separate 'Where input must be a WhereExpression or plain object' error instead, so this message pinpoints null/undefined holes in your clause list. The index in the message is the exact position in the $and/$or array.

Source

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

    (key, value) => new ComparisonWhere(key, "$not_contains", value),
  ],
  ["$regex", (key, value) => new ComparisonWhere(key, "$regex", value)],
  ["$not_regex", (key, value) => new ComparisonWhere(key, "$not_regex", value)],
]);

const parseWhereDict = (data: Record<string, unknown>): WhereExpression => {
  if ("$and" in data) {
    if (Object.keys(data).length !== 1) {
      throw new Error("$and cannot be combined with other keys");
    }
    const rawConditions = data["$and"];
    if (!Array.isArray(rawConditions) || rawConditions.length === 0) {
      throw new TypeError("$and 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(
        (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");
    }

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Remove null/undefined entries before use: clauses.filter(c => c != null)
2. Give disabled filters a neutral clause or build the array only from enabled features (for...of push)
3. Read the reported index to locate the exact offending entry in your $and/$or array

Example fix

// before
const where = { $and: features.map(f => filters[f]) }; // undefined holes

// after
const where = { $and: features.map(f => filters[f]).filter(c => c != null) };

const clauses = rawClauses
  .map(c => (c == null ? undefined : c))
  .filter((c): c is Record<string, unknown> => c != null);
if (clauses.length === 0) throw new Error('empty where clause list');
const where = { $and: clauses };

const isWhereClause = (v: unknown): v is Record<string, unknown> =>
  typeof v === 'object' && v !== null && !Array.isArray(v);

try {
  const results = await collection.query({ where });
} catch (e) {
  if (e instanceof TypeError && /Invalid where clause at index (\d+)/.test(e.message)) {
    const idx = Number(/(\d+)/.exec(e.message)?.[1]);
    return collection.query({ where: { $and: clauses.filter((_, i) => i !== idx) } });
  }
  throw e;
}

When it happens

Trigger: Passing { $and: [{ a: 1 }, null] } — index 1 is null; { $or: [maybeFilterA, maybeFilterB] } where optional filters resolved to undefined; clauses built with map/ternaries that yield undefined for disabled features: conds.map(c => c ? build(c) : undefined).

Common situations: Optional-filter pipelines that map features to clauses and forget to filter out the undefined entries; sparse arrays or deleted indices; API payloads where a filter slot is null meaning 'not applicable'.

Related errors

• $and cannot be combined with other keys
• $and must be a non-empty array
• $or cannot be combined with other keys
• 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/69bf3cab948050f8. Report an issue: GitHub.