chroma-core/chroma · error · ValueError

Invalid field in contains: {', '.join(contains)}, available

Error message

Invalid field in contains: {', '.join(contains)}, available fields: {', '.join(record_set.keys())}

What it means

_validate_record_set_contains (chromadb/api/types.py:511) is the shared precondition of the contains_any/contains_one validators: every field named in the contains set must be an existing key of the record set. It guards against programming errors in code that assembles validator arguments - not against bad end-user data. Public-API users do not see it; it surfaces when custom code invokes the validators with a field name the record set does not have.

Source

Thrown at chromadb/api/types.py:519

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"]
]
IncludeMetadataDocuments: Include = ["metadatas", "documents"]
IncludeMetadataDocumentsEmbeddings: Include = ["metadatas", "documents", "embeddings"]
IncludeMetadataDocumentsEmbeddingsDistances: Include = [
    "metadatas",
    "documents",
    "embeddings",
    "distances",
]
IncludeMetadataDocumentsDistances: Include = ["metadatas", "documents", "distances"]

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Spell field names exactly as the record set keys - print record_set.keys() to see what is available
2. Derive the contains set from shared helpers like get_default_embeddable_record_set_fields() instead of literals
3. Drop fields from the contains set that do not exist for that operation

if not set(contains).issubset(record_set.keys()):
    raise ValueError(f'unknown fields: {set(contains) - set(record_set.keys())}')
validate_record_set_contains_one(record_set, contains)

def valid_contains(record_set, contains) -> bool:
    return all(f in record_set for f in contains)

When it happens

Trigger: Calling validate_record_set_contains_one(record_set, {'documens'}) with a typo; passing {'metadatas'} as a contains field when validating a query record set that has no metadatas key; forks or frameworks that rename record-set fields without updating the contains sets.

Common situations: Typos in field-name sets; assuming all record set types (insert vs query vs update) share the same keys; hard-coded field lists drifting from the actual record set definition.

Related errors

• Attempting to embed a record that already has embeddings.
• At least one of {', '.join(contains_any)} must be provided
• Unequal lengths for fields: {error_str}
• Exactly one of {', '.join(contains_one)} must be provided
• Expected IDs to be a list, got {type(ids).__name__} as IDs

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