chroma-core/chroma · error · ChromaValueError

Expected embeddings to be an array with at least one item

Error message

Expected embeddings to be an array with at least one item

What it means

ChromaValueError thrown by validateEmbeddings (utils.ts:132) when the embeddings array exists but has zero elements ([].length === 0). An add/query batch with no vectors has nothing to send, so the client rejects it before contacting the server.

Source

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

    );
  }
};

const validateEmbeddings = ({
  embeddings,
  fieldName = "embeddings",
}: {
  embeddings: number[][];
  fieldName: string;
}) => {
  if (!Array.isArray(embeddings)) {
    throw new ChromaValueError(
      `Expected '${fieldName}' to be an array, but got ${typeof embeddings}`,
    );
  }

  if (embeddings.length === 0) {
    throw new ChromaValueError(
      "Expected embeddings to be an array with at least one item",
    );
  }

  if (!embeddings.filter((e) => e.every((n: any) => typeof n === "number"))) {
    throw new ChromaValueError(
      "Expected each embedding to be an array of numbers",
    );
  }

  embeddings.forEach((embedding, i) => {
    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}`,
      );
    }
  });
};

View on GitHub (pinned to aecdd12c8a)

Solutions

Omit the embeddings field entirely if you want Chroma to embed documents for you
Guard empty batches: if (!embeddings.length) return / continue
Fix the chunker to skip zero-length tail chunks

Example fix

// before
await collection.add({ ids, embeddings: [], documents });
// after
await collection.add({ ids, documents }); // server/client embeds documents

Defensive patterns

Strategy: validation

Validate before calling

if (Array.isArray(embeddings) && embeddings.length === 0) return; // skip empty batch

Type guard

const hasVectors = (embs) => Array.isArray(embs) && embs.length > 0;

Try / catch

try { await collection.query({ queryEmbeddings: embs, nResults: k }); } catch (e) { if (e instanceof ChromaValueError && /at least one item/.test(e.message)) return { results: [] }; else throw e; }

Prevention

Guard chunkers against emitting zero-length tail chunks
Omit embeddings entirely when you want documents auto-embedded
Return empty results early from search endpoints with no queries

When it happens

Trigger: collection.add({ ids, embeddings: [], documents }) — embeddings explicitly empty; query({ queryEmbeddings: [] }); a batching step that produced an empty vectors array for this chunk.

Common situations: Chunking code that emits a final empty chunk; filtering out failed embeddings leaving []; passing embeddings when you meant to let documents be embedded (omit the field instead).

Related errors

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