chroma-core/chroma · error · ValueError

Expected include item to be one of {', '.join(valid_items)},

Error message

Expected include item to be one of {', '.join(valid_items)}, got {item}

What it means

Every include item must be one of the literal values of the Include type: documents, embeddings, metadatas, distances, uris, data. validate_include extracts these via typing.get_args and rejects anything else, including close typos like "document", "embedding", or "ids".

Source

Thrown at chromadb/api/types.py:1348

            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:
    """Validates n_results to ensure it is a positive Integer. Since hnswlib does not allow n_results to be negative."""
    # Check Number of requested results
    if not isinstance(n_results, int):
        raise ValueError(
            f"Expected requested number of results to be a int, got {n_results}"
        )
    if n_results <= 0:
        raise TypeError(

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Use exactly one of: "documents", "embeddings", "metadatas", "distances", "uris", "data"
2. Fix singular typos: "document" → "documents", "metadata" → "metadatas"
3. Remove "ids" from include — ids are returned automatically in every result

Example fix

# before
results = collection.query(query_embeddings=[q], include=["document", "ids"])

# after
results = collection.query(query_embeddings=[q], include=["documents", "metadatas"])  # ids always returned

VALID_INCLUDE = {"documents", "embeddings", "metadatas", "distances", "uris", "data"}

def validate_include_items(include: list[str]) -> list[str]:
    bad = [i for i in include if i not in VALID_INCLUDE]
    if bad:
        raise ValueError(f"invalid include items {bad}; valid: {sorted(VALID_INCLUDE)}")
    return include

res = collection.query(query_embeddings=[q], include=validate_include_items(include), n_results=5)

from typing import Literal, get_args
from chromadb.api.types import Include

VALID = set(get_args(get_args(Include)[0]))

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

try:
    res = collection.get(ids=ids, include=include)
except ValueError as e:
    if "Expected include item to be one of" in str(e):
        raise ValueError(f"check plurals: {include}; valid = documents, embeddings, metadatas, distances, uris, data") from e
    raise

When it happens

Trigger: include=["document"] (singular typo), include=["ids"] (ids are always returned and not includable), include=["metadata"], or include=["embeddings", "score"]. Raised on collection.get() and collection.query() calls.

Common situations: Singular/plural confusion — the API uses plurals (documents, metadatas, embeddings); porting code from other vector DBs whose field names differ (e.g. "score" or "vector"); auto-complete picking the wrong token.

Related errors

• Failed to fetch ${input} with status ${resp.status}: ${resp.
• Expected include to be a list, got {include}
• Expected include item to be a str, got {item}
• Include item cannot be one of {', '.join(dissalowed)}, got {
• Multiple embedding functions provided. Please provide only o

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