chroma-core/chroma · error · ChromaValueError

Expected '${fieldName}' to be an array, but got ${typeof doc

Error message

Expected '${fieldName}' to be an array, but got ${typeof documents}

What it means

ChromaValueError thrown by validateDocuments (utils.ts:166) via validateBaseRecordSet when the documents value is not an Array. fieldName is 'documents' for add/update and 'queryTexts' for query, so the message tells you which call site is at fault.

Source

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

    if (embedding.length === 0) {
      throw new ChromaValueError(
        `Expected each embedding to be a non-empty array of numbers, but got an empty array at index ${i}`,
      );
    }
  });
};

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

View on GitHub (pinned to aecdd12c8a)

Solutions

Wrap scalars in an array: documents: [doc]
Keep the field typed as (string|null|undefined)[] so TS flags misuse
Normalize loader output with Array.isArray checks at the boundary

Example fix

// before
await collection.add({ ids: ['1'], documents: 'hello world' });
// after
await collection.add({ ids: ['1'], documents: ['hello world'] });

Defensive patterns

Strategy: type-guard

Validate before calling

if (!Array.isArray(documents)) throw new TypeError(`documents must be an array, got ${typeof documents}`);

Type guard

const isDocumentList = (v) => Array.isArray(v);

Try / catch

try { await collection.add({ ids, documents }); } catch (e) { if (e instanceof ChromaValueError && /'documents' to be an array|'queryTexts' to be an array/.test(e.message)) documents = [documents]; else throw e; }

Prevention

Wrap single strings in [] at the API boundary
Keep documents typed as (string|null|undefined)[]
Normalize loader outputs with Array.isArray checks

When it happens

Trigger: Passing a bare string: collection.add({ ids, documents: 'hello' }) instead of ['hello']; passing an object or Map produced by a loader; query({ queryTexts: someString }).

Common situations: Single-record convenience expectation (many SDKs accept a string); refactors that change a variable from string[] to string; query text taken from req.body.q and passed unwrapped.

Related errors

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