What causes "Non-empty lists are required for ${zeroLength.join(", ")}" in chroma-core/chroma?

Guard the call: skip when any provided array is empty (if (!ids.length || !documents.length) return)

chroma-core/chroma · error · ChromaValueError

Non-empty lists are required for ${zeroLength.join(", ")}

Error message

Non-empty lists are required for ${zeroLength.join(", ")}

What it means

ChromaValueError thrown by validateRecordSetLengthConsistency (utils.ts:100-106) from Collection.prepareRecords when at least one record-set field was provided but at least one of the provided arrays is empty ([]). An empty array cannot be aligned with any other array length, so the batch is rejected before the request is sent.

Source

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

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

const validateEmbeddings = ({
  embeddings,
  fieldName = "embeddings",
}: {
  embeddings: number[][];

View on GitHub (pinned to aecdd12c8a)

Solutions

Guard the call: skip when any provided array is empty (if (!ids.length || !documents.length) return)
Make upstream filtering all-or-nothing so the arrays stay row-aligned
Log the offending field names from the error — the message lists exactly which arrays were empty

Example fix

// before
await collection.add({ ids, documents }); // ids === []
// after
if (ids.length === 0 || documents.length === 0) return;
await collection.add({ ids, documents });

Defensive patterns

Strategy: validation

Validate before calling

function noEmptyArrays(rs) { return Object.entries(rs).every(([f, v]) => v === undefined || (Array.isArray(v) && v.length > 0)); }

Type guard

function isBatchable(rs) { return ['ids','embeddings','metadatas','documents','uris'].every(f => { const v = rs[f]; return v === undefined || (Array.isArray(v) && v.length > 0); }); }

Try / catch

try { await collection.add(rs); } catch (e) { if (e instanceof ChromaValueError && /Non-empty lists are required/.test(e.message)) { console.warn('Skipped empty batch'); return; } throw e; }

Prevention

Skip the call when any provided array is empty
Keep filtering all-or-nothing across row-aligned arrays
Log the field list from the message to locate the empty producer

When it happens

Trigger: collection.add({ ids: [], documents: ['a'] }) or any call where a provided field among ids/embeddings/metadatas/documents/uris has length 0 (e.g. await collection.add({ ids: filteredIds, documents: docs }) where filteredIds is []).

Common situations: A filter/map step upstream removes all elements of one array but not the others; early-return code omitted for empty pages from a paginator; conditionally building arrays where one branch pushes nothing.

Related errors

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