chroma-core/chroma · error · ChromaValueError

At least one of ${recordSetFields.join(", ")} must be provid

Error message

At least one of ${recordSetFields.join(", ")} must be provided

What it means

ChromaValueError thrown by validateRecordSetLengthConsistency (utils.ts:87), called at the top of Collection.prepareRecords — the shared preparation step for collection.add() and collection.update(). Every record-set field (ids, embeddings, metadatas, documents, uris) was undefined/absent, so there is nothing to insert or update and no length to validate against. Thrown client-side before any network traffic.

Source

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

  }
  return undefined;
};

/**
 * Validates that all arrays in a RecordSet have consistent lengths.
 * @param recordSet - The record set to validate
 * @throws ChromaValueError if arrays have inconsistent lengths or are empty
 */
export const validateRecordSetLengthConsistency = (recordSet: RecordSet) => {
  const lengths: [string, number][] = Object.entries(recordSet)
    .filter(
      ([field, value]) =>
        recordSetFields.includes(field) && value !== undefined,
    )
    .map(([field, value]) => [field, value.length]);

  if (lengths.length === 0) {
    throw new ChromaValueError(
      `At least one of ${recordSetFields.join(", ")} must be provided`,
    );
  }

  const zeroLength = lengths
    .filter(([_, length]) => length === 0)
    .map(([field, _]) => field);
  if (zeroLength.length > 0) {
    throw new ChromaValueError(
      `Non-empty lists are required for ${zeroLength.join(", ")}`,
    );
  }

  if (new Set(lengths.map(([_, length]) => length)).size > 1) {
    throw new ChromaValueError(
      `Unequal lengths for fields ${lengths
        .map(([field, _]) => field)
        .join(", ")}`,

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Ensure at least one of ids, embeddings, metadatas, documents, uris is a non-undefined array — normally ids is required for add/update anyway
2. Skip the API call entirely when the incoming batch is empty: if (!batch.ids?.length) return
3. Check field spelling/casing against the RecordSet type (ids, documents, metadatas, embeddings, uris)

Example fix

// before
await collection.add({});
// after
if (!records.ids?.length) return; // nothing to add
await collection.add({ ids: records.ids, documents: records.documents });

const FIELDS = ['ids','embeddings','metadatas','documents','uris'];
function hasAnyRecordSetField(rs) { return FIELDS.some(f => rs[f] !== undefined); }

function isNonEmptyRecordSet(rs) { return FIELDS.some(f => Array.isArray(rs[f]) && rs[f].length > 0); }

try { await collection.add(rs); } catch (e) { if (e instanceof ChromaValueError && /At least one of/.test(e.message)) return; else throw e; }

When it happens

Trigger: await collection.add({ metadatas: undefined, documents: undefined, ids: undefined }) — i.e. an object where all five recordSetFields are undefined; also collection.add({}) or passing an accidentally-empty object built from empty spreads.

Common situations: Building a RecordSet dynamically (e.g. filtering rows then spreading) and every field ends up undefined; an empty upstream batch from a loader that yields zero records; typos like {ID: [...]} (wrong casing) leaving the real fields undefined.

Related errors

• Non-empty lists are required for ${zeroLength.join(", ")}
• Unequal lengths for fields ${lengths.map(([field, _]) => fie
• Deleting FTS index is only supported on #document key.
• Cannot disable all index types for key '${key}'. Please spec
• Expected '${fieldName}' to be an array, but got ${typeof emb

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