chroma-core/chroma · error · ChromaValueError

At least one of '${embeddingsField}' and '${documentsField}'

Error message

At least one of '${embeddingsField}' and '${documentsField}' must be provided

What it means

validateBaseRecordSet (with update=false) throws when a record set has neither embeddings nor documents — every added record must carry content to embed or a precomputed vector. The check runs client-side before any request. It is relaxed in update mode (update=true), where partial record sets are legitimate.

Source

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

 * @param options.recordSet - The record set to validate
 * @param options.update - Whether this is for an update operation (relaxes requirements)
 * @param options.embeddingsField - Name of the embeddings field for error messages
 * @param options.documentsField - Name of the documents field for error messages
 * @throws ChromaValueError if validation fails
 */
export const validateBaseRecordSet = ({
  recordSet,
  update = false,
  embeddingsField = "embeddings",
  documentsField = "documents",
}: {
  recordSet: BaseRecordSet;
  update?: boolean;
  embeddingsField?: string;
  documentsField?: string;
}) => {
  if (!recordSet.embeddings && !recordSet.documents && !update) {
    throw new ChromaValueError(
      `At least one of '${embeddingsField}' and '${documentsField}' must be provided`,
    );
  }

  if (recordSet.embeddings) {
    validateEmbeddings({
      embeddings: recordSet.embeddings,
      fieldName: embeddingsField,
    });
  }

  if (recordSet.documents) {
    validateDocuments({
      documents: recordSet.documents,
      fieldName: documentsField,
    });
  }

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Include a documents array (one string per id) so the collection's embedding function runs.
2. Or include embeddings (one vector per id) when you pre-computed them.
3. If you intentionally modify existing records, use the update path (update/upsert semantics) rather than add().

Example fix

// before
await collection.add({ ids: ['1'], metadatas: [{ a: 1 }] });

// after
await collection.add({ ids: ['1'], documents: ['text for record 1'], metadatas: [{ a: 1 }] });

if (!records.embeddings && !records.documents) {
  throw new Error('add() requires documents or embeddings for every record');
}
await collection.add(records);

const hasRecordContent = (rs: { embeddings?: unknown; documents?: unknown }) =>
  Boolean(rs.embeddings || rs.documents);

try {
  await collection.add(records);
} catch (e) {
  if ((e as Error).message.includes('must be provided')) {
    // attach documents or embeddings, then retry; or switch to an update path
  } else {
    throw e;
  }
}

When it happens

Trigger: collection.add({ ids: ['1'], metadatas: [{ a: 1 }] }) — ids and metadata only. documents ending up undefined because a mapping step failed. Using add() when you meant to update existing records with partial data.

Common situations: Ingestion pipelines that pre-compute metadata but forget content; conditionally built option objects where both branches leave the fields unset; assuming the server will attach documents later.

Related errors

• embeddings and documents cannot both be undefined
• Failed to generate embeddings for your request.
• The model name cannot be changed after initialization.
• The task type cannot be changed after initialization.
• Changing the URL is not allowed.

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