chroma-core/chroma · error · ChromaValueError

Expected 'include' items to be one of ${validValues.join(",

Error message

Expected 'include' items to be one of ${validValues.join(", ")}, but got ${item}

What it means

Include items must be one of the IncludeEnum keys — documents, embeddings, metadatas, distances, uris (types.ts:183-194; the message interpolates Object.keys(IncludeEnum)). Anything else throws this ChromaValueError listing the valid values (utils.ts:733-739). 'ids' is not includeable because ids are always returned.

Source

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

export const validateInclude = ({
  include,
  exclude,
}: {
  include: Include[];
  exclude?: Include[];
}) => {
  if (!Array.isArray(include)) {
    throw new ChromaValueError("Expected 'include' to be a non-empty array");
  }

  const validValues = Object.keys(IncludeEnum);
  include.forEach((item) => {
    if (typeof (item as any) !== "string") {
      throw new ChromaValueError("Expected 'include' items to be strings");
    }

    if (!validValues.includes(item)) {
      throw new ChromaValueError(
        `Expected 'include' items to be one of ${validValues.join(
          ", ",
        )}, but got ${item}`,
      );
    }

    if (exclude?.includes(item)) {
      throw new ChromaValueError(`${item} is not allowed for this operation`);
    }
  });
};

/**
 * Validates the number of results parameter for queries.
 * @param nResults - Number of results to validate
 * @throws ChromaValueError if nResults is not a positive number
 */
export const validateNResults = (nResults: number) => {

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Use exactly the plural forms: documents, embeddings, metadatas, distances, uris
2. Reference IncludeEnum members instead of hand-typed strings
3. Remove 'ids' from the list — ids are always included in results

Example fix

// before
await col.get({ include: ['ids', 'metadata'] });

// after
await col.get({ include: ['metadatas'] }); // ids always returned

import { IncludeEnum } from 'chromadb';
const VALID_INCLUDE = Object.keys(IncludeEnum); // ['distances','documents','embeddings','metadatas','uris']
const safeInclude = requested.filter(f => VALID_INCLUDE.includes(f));
if (safeInclude.length === 0) safeInclude.push('documents');
await col.get({ include: safeInclude });

import { IncludeEnum, type Include } from 'chromadb';
const isIncludeValue = (v: unknown): v is Include =>
  typeof v === 'string' && Object.values(IncludeEnum).includes(v as IncludeEnum);

When it happens

Trigger: include: ['ids']; include: ['metadata'] (singular); include: ['content'] or ['data'] — against collection.get() or collection.query().

Common situations: Assuming ids must be requested explicitly; singular/plural typos; porting code from another vector store with different result-field names.

Related errors

• Expected 'include' to be a non-empty array
• Expected 'include' items to be strings
• Expected 'whereDocument' to have exactly one operator, but g
• Expected 'whereDocument' operator to be one of $contains, $n
• Expected operand for ${operator} to be a list of 'whereDocum

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