chroma-core/chroma · error · ValueError

Input must be a list of text documents (str) or a list of im

Error message

Input must be a list of text documents (str) or a list of images (numpy arrays).

What it means

This is the catch-all of __call__'s dispatch: the batch is neither all documents nor all images, and it is not even a mix of the two - no element qualifies as a str document or an image. Typical elements are dicts, ints, None, bytes, or row objects whose text field was never extracted.

Source

Thrown at chromadb/utils/embedding_functions/cohere_embedding_function.py:126

            return [
                np.array(embeddings, dtype=np.float32)
                for embeddings in self.client.embed(
                    images=base64_images,
                    model=self.model_name,
                    input_type="image",
                ).embeddings
            ]
        else:
            # Check if it's a mix or neither
            has_texts = any(is_document(item) for item in input)
            has_images = any(is_image(item) for item in input)
            if has_texts and has_images:
                raise ValueError(
                    "Input contains a mix of text documents and images, which is not supported. Provide either all texts or all images."
                )
            else:
                raise ValueError(
                    "Input must be a list of text documents (str) or a list of images (numpy arrays)."
                )

    @staticmethod
    def name() -> str:
        return "cohere"

    def default_space(self) -> Space:
        if self.model_name == "embed-multilingual-v2.0":
            return "ip"
        return "cosine"

    def supported_spaces(self) -> List[Space]:
        if self.model_name == "embed-english-v2.0":
            return ["cosine"]
        elif self.model_name == "embed-english-light-v2.0":
            return ["cosine"]
        elif self.model_name == "embed-multilingual-v2.0":

View on GitHub (pinned to aecdd12c8a)

Solutions

Coerce items to str explicitly: ef([str(x) for x in items]) when text was intended.
Extract the text field from structured records before embedding (e.g. [r['text'] for r in rows]).
Validate upstream that every element is str or np.ndarray and drop None/empty placeholders.

Example fix

# before
ef([{'text': 'hello'}, {'text': 'world'}])  # ValueError: must be str or ndarrays

# after
docs = [r['text'] for r in records]
ef(docs)

Defensive patterns

Strategy: type-guard

Validate before calling

import numpy as np
if not all(isinstance(x, (str, np.ndarray)) for x in batch):
    batch = [x['text'] if isinstance(x, dict) else str(x) for x in batch]

Type guard

import numpy as np

def is_embeddable_batch(batch: list) -> bool:
    return len(batch) > 0 and all(isinstance(x, (str, np.ndarray)) for x in batch)

Try / catch

try:
    embs = ef(batch)
except ValueError as e:
    if 'must be a list of text documents' in str(e):
        embs = ef([str(x) for x in batch])  # or extract the right field upstream
    else:
        raise

Prevention

Extract text fields from structured records before embedding.
Filter None/empty placeholders out of batches at load time.
Keep a single validated input type at the pipeline boundary.

When it happens

Trigger: ef([{'text': 'hello'}]), ef([1, 2, 3]), ef([None]), or ef([b'raw bytes']) - nothing in the list is a str or an ndarray image.

Common situations: Forgetting to extract a field before embedding parsed JSON/DB rows; passing None placeholders for empty documents; reading files as bytes without decoding; passing objects that fail both is_document and is_image checks.

Related errors

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