chroma-core/chroma · error · ValueError

Expected include to be a list, got {include}

Error message

Expected include to be a list, got {include}

What it means

The include parameter of collection.get/query must be a Python list. validate_include rejects any non-list (a bare string, tuple, set, or None) with this ValueError. Valid items are the literals documents, embeddings, metadatas, distances, uris, data.

Source

Thrown at chromadb/api/types.py:1340

            for where_document_expression in operand:
                validate_where_document(where_document_expression)
        # Value is $contains/$not_contains/$regex/$not_regex operator
        elif not isinstance(operand, str):
            raise ValueError(
                f"Expected where document operand value for operator {operator} to be a str, got {operand}"
            )
        elif len(operand) == 0:
            raise ValueError(
                f"Expected where document operand value for operator {operator} to be a non-empty str"
            )


def validate_include(include: Include, dissalowed: Optional[Include] = None) -> None:
    """Validates include to ensure it is a list of strings. Since get does not allow distances, allow_distances is used
    to control if distances is allowed"""

    if not isinstance(include, list):
        raise ValueError(f"Expected include to be a list, got {include}")
    for item in include:
        if not isinstance(item, str):
            raise ValueError(f"Expected include item to be a str, got {item}")

        # Get the valid items from the Literal type inside the List
        valid_items = get_args(get_args(Include)[0])
        if item not in valid_items:
            raise ValueError(
                f"Expected include item to be one of {', '.join(valid_items)}, got {item}"
            )

        if dissalowed is not None and any(item == e for e in dissalowed):
            raise ValueError(
                f"Include item cannot be one of {', '.join(dissalowed)}, got {item}"
            )


def validate_n_results(n_results: int) -> int:

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Wrap the value in a list: include=["documents"]
2. If the value may arrive as either form, normalize first: include = [include] if isinstance(include, str) else list(include)
3. Omit include entirely to accept the default (documents + metadatas) when you don't need custom fields

Example fix

# before
results = collection.get(ids=["1"], include="metadatas")

# after
results = collection.get(ids=["1"], include=["metadatas"])

def normalize_include(include):
    if include is None:
        return ["documents", "metadatas"]
    if isinstance(include, str):
        include = [include]
    if not isinstance(include, list):
        raise TypeError(f"include must be a list, got {type(include).__name__}")
    return list(include)

res = collection.get(ids=ids, include=normalize_include(raw_include))

from typing import Any

def is_valid_include(include: Any) -> bool:
    return isinstance(include, list) and all(isinstance(i, str) for i in include)

try:
    res = collection.get(ids=ids, include=include)
except ValueError as e:
    if "Expected include to be a list" in str(e) and isinstance(include, str):
        res = collection.get(ids=ids, include=[include])  # self-heal a bare string
    else:
        raise

When it happens

Trigger: collection.get(include="documents") (bare string instead of list), include=("documents", "metadatas") (tuple — fails isinstance(x, list) even though it looks array-like), or include=None reaching validation.

Common situations: Muscle memory from APIs that accept a single string; JSON configs deserialized as a string instead of an array; typed clients (TypeScript/Java) serializing a one-element array as a scalar.

Related errors

• Expected include item to be a str, got {item}
• Expected where document operand value for operator {operator
• Expected embeddings to be a list, got {type(embeddings).__na
• Expected documents to be a list, got {type(documents).__name
• Expected '${fieldName}' to be an array, but got ${typeof emb

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