chroma-core/chroma · error · ChromaValueError

Expected 'include' items to be strings

Error message

Expected 'include' items to be strings

What it means

Every element of the include array must be a string (a key of IncludeEnum); validateInclude's forEach throws this ChromaValueError for numbers, null, objects, or symbols (utils.ts:728-731). The check runs before the enum-membership check, so non-strings fail with this message rather than the 'one of' message.

Source

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

 * @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`);
    }
  });
};

/**
 * Validates the number of results parameter for queries.

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Validate before the call: include.every(v => typeof v === 'string')
2. Type the variable as Include[] using the package's exported types
3. Convert foreign field names to IncludeEnum values at the config boundary

Example fix

// before
await col.get({ include: [1, 2] });

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

function normalizeInclude(raw: unknown): string[] {
  const list = Array.isArray(raw) ? raw : [raw];
  if (!list.every(v => typeof v === 'string')) {
    throw new TypeError('include items must be strings');
  }
  return list as string[];
}

const isStringIncludeList = (v: unknown): v is string[] =>
  Array.isArray(v) && v.every(item => typeof item === 'string');

When it happens

Trigger: include: [1]; include: [null]; include: [{}] — usually values that arrived untyped from JSON config, URL query params, or another API's field indices.

Common situations: Loading include lists from user-supplied configuration; mapping another vector DB's numeric field selectors directly into Chroma include.

Related errors

• Expected 'include' to be a non-empty array
• Expected 'include' items to be one of ${validValues.join(",
• Expected 'nResults' to be a number, but got ${typeof nResult
• Expected 'whereDocument' to have exactly one operator, but g
• Expected 'whereDocument' operator to be one of $contains, $n

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