chroma-core/chroma · error · ChromaValueError

Expected 'ids' to be an array, but got ${typeof ids}

Error message

Expected 'ids' to be an array, but got ${typeof ids}

What it means

ChromaValueError thrown by validateIDs (utils.ts:190) when the ids value is not an Array. validateIDs runs in Collection.prepareRecords (add/update) and also on get/delete/modify paths whenever ids is provided, so this fires client-side across most collection operations.

Source

Thrown at clients/new-js/packages/chromadb/src/utils.ts:190

  }

  documents.forEach((document) => {
    if (!nullable && typeof document !== "string" && !document) {
      throw new ChromaValueError(
        `Expected each document to be a string, but got ${typeof document}`,
      );
    }
  });
};

/**
 * Validates an array of IDs for type correctness and uniqueness.
 * @param ids - Array of ID strings to validate
 * @throws ChromaValueError if IDs are not strings, empty, or contain duplicates
 */
export const validateIDs = (ids: string[]) => {
  if (!Array.isArray(ids)) {
    throw new ChromaValueError(
      `Expected 'ids' to be an array, but got ${typeof ids}`,
    );
  }

  if (ids.length === 0) {
    throw new ChromaValueError("Expected 'ids' to be a non-empty list");
  }

  const nonStrings = ids
    .map((id, i) => [id, i] as [any, number])
    .filter(([id, _]) => typeof id !== "string")
    .map(([_, i]) => i);

  if (nonStrings.length > 0) {
    throw new ChromaValueError(
      `Found non-string IDs at ${nonStrings.join(", ")}`,
    );
  }

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. Wrap or convert: Array.isArray(x) ? x : [x]; for Sets use [...set]
  2. Type ids as string[] at the API boundary
  3. Parse joined strings with .split(',') before calling

Example fix

// before
await collection.get({ ids: req.query.ids }); // 'a,b' string
// after
await collection.get({ ids: String(req.query.ids).split(",") });
Defensive patterns

Strategy: type-guard

Validate before calling

if (!Array.isArray(ids)) throw new TypeError(`ids must be an array, got ${typeof ids}`);

Type guard

const isIdArray = (v) => Array.isArray(v);

Try / catch

try { await collection.get({ ids }); } catch (e) { if (e instanceof ChromaValueError && /'ids' to be an array/.test(e.message)) ids = Array.from(ids); else throw e; }

Prevention

When it happens

Trigger: collection.add({ ids: 'abc', documents: ['x'] }) — a single string id; collection.get({ ids: idSet }) where idSet is a Set; ids as a number or object from user input.

Common situations: Passing a Set or generator where an array is required; single-id convenience assumptions; ids arriving as one comma-joined string from a URL param.

Related errors

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