chroma-core/chroma · error · ValueError

Exactly one of {', '.join(contains_one)} must be provided

Error message

Exactly one of {', '.join(contains_one)} must be provided

What it means

validate_record_set_contains_one (chromadb/api/types.py:501), reached via validate_record_set_for_embedding, requires exactly one embeddable field to be present whenever Chroma must generate embeddings itself. For add/upsert/query the embeddable set is {'documents','images','uris'}; for update it is {'documents','images'}. Supplying none (nothing to embed) or more than one (ambiguous input) both raise this error. Passing explicit embeddings bypasses the check entirely.

Source

Thrown at chromadb/api/types.py:509

) -> None:
    """
    Validates that at least one of the fields in contains_any is not None.
    """
    _validate_record_set_contains(record_set, contains_any)

    if not any(record_set[field] is not None for field in contains_any):  # type: ignore[literal-required]
        raise ValueError(f"At least one of {', '.join(contains_any)} must be provided")


def validate_record_set_contains_one(
    record_set: BaseRecordSet, contains_one: Set[str]
) -> None:
    """
    Validates that exactly one of the fields in contains_one is not None.
    """
    _validate_record_set_contains(record_set, contains_one)
    if sum(record_set[field] is not None for field in contains_one) != 1:  # type: ignore[literal-required]
        raise ValueError(f"Exactly one of {', '.join(contains_one)} must be provided")


def _validate_record_set_contains(
    record_set: BaseRecordSet, contains: Set[str]
) -> None:
    """
    Validates that all fields in contains are valid fields of the Record.
    """
    if any(field not in record_set for field in contains):
        raise ValueError(
            f"Invalid field in contains: {', '.join(contains)}, available fields: {', '.join(record_set.keys())}"
        )


Parameter = TypeVar("Parameter", Document, Image, Embedding, Metadata, ID)

Include = List[
    Literal["documents", "embeddings", "metadatas", "distances", "uris", "data"]

View on GitHub (pinned to aecdd12c8a)

Solutions

1. If you want Chroma to embed: pass exactly one of documents, images or uris (typically documents)
2. If you already have vectors: pass embeddings= explicitly - documents then become optional payload
3. In query code, branch: use query_embeddings when available, otherwise exactly one of query_texts/query_images/query_uris
4. If you genuinely need metadata-only rows, reconsider whether a vector store fits, or store explicit placeholder embeddings

Example fix

# before
collection.add(ids=ids, metadatas=metas)  # nothing to embed

# after
collection.add(ids=ids, metadatas=metas, documents=docs)  # exactly one embeddable field

provided = [name for name, v in {'documents': documents, 'images': images, 'uris': uris}.items() if v is not None]
if embeddings is None and len(provided) != 1:
    raise ValueError(f'pass exactly one of documents/images/uris (got {provided}) or supply embeddings')
collection.add(ids=ids, embeddings=embeddings, documents=documents, images=images, uris=uris)

def exactly_one_embeddable(documents, images, uris) -> bool:
    return sum(v is not None for v in (documents, images, uris)) == 1

try:
    collection.query(query_texts=qtexts, query_embeddings=qembs, n_results=k)
except ValueError as e:
    if 'Exactly one of' in str(e):
        # pick one input mode and retry
        ...
    raise

When it happens

Trigger: collection.query() with none of query_texts/query_embeddings/query_images/query_uris; collection.add(ids=[...], metadatas=[...]) with no embeddings, documents, images or uris (nothing to embed); collection.add(documents=[...], uris=[...]) (two embeddable fields); query(query_texts=[...], query_images=[...]); update(ids, documents=[...], images=[...]).

Common situations: Adding id-only or metadata-only records and expecting Chroma to accept them without vectors; generic search code that passes both text and image queries; forgetting that add() needs content to embed unless embeddings are supplied; code migrated from older versions with looser checks.

Related errors

• Attempting to embed a record that already has embeddings.
• embeddings and documents cannot both be undefined
• Expected '${fieldName}' to be an array, but got ${typeof emb
• Expected embeddings to be an array with at least one item
• Expected each embedding to be an array of numbers

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