chroma-core/chroma · error · ChromaValueError

Expected 'include' to be a non-empty array

Error message

Expected 'include' to be a non-empty array

What it means

The include option of collection.get() and query() must be an array of IncludeEnum values; validateInclude throws this ChromaValueError when Array.isArray(include) is false (utils.ts:723-725). Only array-ness is checked at this step — a bare string like 'documents', a single unwrapped enum member, or an object all fail here.

Source

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

  }
};

/**
 * Validates include fields for query operations.
 * @param options - Validation options
 * @param options.include - Array of fields to include in results
 * @param options.exclude - Optional array of fields that should not be included
 * @throws ChromaValueError if include fields are invalid
 */
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`);

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Always pass an array: include: ['documents', 'metadatas']
2. Use IncludeEnum members as elements: include: [IncludeEnum.Documents]
3. Normalize untyped config at the boundary: include: [].concat(rawInclude)

Example fix

// before
await col.get({ include: 'metadatas' });

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

const includeList = Array.isArray(rawInclude) ? rawInclude : [rawInclude];
await col.get({ include: includeList });

import { IncludeEnum, type Include } from 'chromadb';
const isIncludeArray = (v: unknown): v is Include[] =>
  Array.isArray(v) && v.every(i => typeof i === 'string' && i in IncludeEnum);

When it happens

Trigger: collection.get({ include: 'documents' }); include: IncludeEnum.Documents (single value not wrapped in brackets); include: { documents: true } — typical when the value comes from parsed JSON or env config.

Common situations: Reading include from user-supplied JSON where a single field was given as a scalar; forgetting the brackets when only one field is requested.

Related errors

• Expected 'include' items to be strings
• Expected 'include' items to be one of ${validValues.join(",
• 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/ca122b93425b000e. Report an issue: GitHub.