chroma-core/chroma · error · ChromaValueError

Expected '${fieldName}' to be a non-empty list

Error message

Expected '${fieldName}' to be a non-empty list

What it means

ChromaValueError thrown by validateDocuments (utils.ts:169) when the documents array is present but empty ([]). A batch with no documents cannot be added, updated, or queried, so the client rejects it before any request.

Source

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

};

const validateDocuments = ({
  documents,
  nullable = false,
  fieldName = "documents",
}: {
  documents: (string | null | undefined)[];
  fieldName: string;
  nullable?: boolean;
}) => {
  if (!Array.isArray(documents)) {
    throw new ChromaValueError(
      `Expected '${fieldName}' to be an array, but got ${typeof documents}`,
    );
  }

  if (documents.length === 0) {
    throw new ChromaValueError(
      `Expected '${fieldName}' to be a non-empty list`,
    );
  }

  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
 */

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Skip the call when documents is empty: if (!documents.length) return
2. Guard at the API boundary (e.g. HTTP handler returns 400 before touching Chroma)
3. Omit the documents field if you intend to pass embeddings only

Example fix

// before
await collection.query({ queryTexts: [], nResults: 5 });
// after
if (queryTexts.length === 0) return { results: [] };
await collection.query({ queryTexts, nResults: 5 });

if (Array.isArray(documents) && documents.length === 0) return { results: [] };

const hasDocuments = (d) => Array.isArray(d) && d.length > 0;

try { await collection.query({ queryTexts: texts, nResults: 5 }); } catch (e) { if (e instanceof ChromaValueError && /non-empty list/.test(e.message)) return { results: [] }; else throw e; }

When it happens

Trigger: collection.add({ ids, documents: [] }); query({ queryTexts: [] }); documents arrays emptied by an upstream filter.

Common situations: Search endpoints queried with an empty list of terms; ingestion loops hitting an empty page; conditionally building documents from rows where none matched.

Related errors

• Non-empty lists are required for ${zeroLength.join(", ")}
• Expected embeddings to be an array with at least one item
• Expected each embedding to be a non-empty array of numbers,
• Expected '${fieldName}' to be an array, but got ${typeof doc
• Expected each document to be a string, but got ${typeof docu

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