chroma-core/chroma · error · ChromaValueError

Found non-string IDs at ${nonStrings.join(", ")}

Error message

Found non-string IDs at ${nonStrings.join(", ")}

What it means

ChromaValueError thrown by validateIDs (utils.ts:203) when some elements of the ids array are not strings. The message lists the indexes of every offending element (not the values), so you can locate them in the original array.

Source

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

 */
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(", ")}`,
    );
  }

  const seen = new Set();
  const duplicates = ids.filter((id) => {
    if (seen.has(id)) {
      return id;
    }
    seen.add(id);
  });
  let message = "Expected IDs to be unique, but found duplicates of";
  if (duplicates.length > 0 && duplicates.length <= 5) {
    throw new ChromaValueError(`${message} ${duplicates.join(", ")}`);
  }
  if (duplicates.length > 0) {
    throw new ChromaValueError(
      `${message} ${duplicates.slice(0, 5).join(", ")}, ..., ${duplicates

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. Convert all ids to strings at the source: rows.map(r => String(r.id))
  2. Use the reported indices to inspect the exact bad entries before retrying
  3. Enforce id: string in the types of your ingestion pipeline

Example fix

// before
await collection.add({ ids: [1, 2, 3], documents });
// after
await collection.add({ ids: [1, 2, 3].map(String), documents });
Defensive patterns

Strategy: type-guard

Validate before calling

const nonStringIdx = ids.map((id, i) => [id, i]).filter(([id]) => typeof id !== 'string').map(([, i]) => i);
if (nonStringIdx.length) throw new TypeError(`Non-string ids at ${nonStringIdx}`);

Type guard

function isStringIdArray(v): v is string[] { return Array.isArray(v) && v.every(id => typeof id === 'string'); }

Try / catch

try { await collection.add({ ids, documents }); } catch (e) { if (e instanceof ChromaValueError && /non-string IDs at/.test(e.message)) ids = ids.map(String); else throw e; }

Prevention

When it happens

Trigger: collection.add({ ids: [1, 2, 3], documents }); collection.get({ ids: ['a', 42] }); ids mapped from database numeric primary keys without String() conversion.

Common situations: Numeric auto-increment IDs from SQL sources; Object.entries keys (strings) mixed with values; ids parsed from JSON where the field is sometimes a number.

Related errors

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