chroma-core/chroma · error · ValueError

Include item cannot be one of {', '.join(dissalowed)}, got {

Error message

Include item cannot be one of {', '.join(dissalowed)}, got {item}

What it means

Some call sites pass a disallowed set to validate_include (note the misspelled parameter name 'dissalowed' in the source). Collection.get() disallows "distances" because distances only exist for nearest-neighbor queries, so get(include=["distances"]) raises this ValueError. Query() passes no disallowed items.

Source

Thrown at chromadb/api/types.py:1353

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(
            f"Number of requested results {n_results}, cannot be negative, or zero."
        )
    return n_results

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Remove "distances" from include when calling collection.get(); distances are only valid in collection.query()
2. Use separate constants: one for get (documents/metadatas/embeddings/uris/data) and one for query (adds distances)
3. If you need similarity scores, switch the call to query() with query_embeddings instead of get()

Example fix

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

# after
results = collection.get(ids=["1", "2"], include=["documents"])
# distances only via query:
# results = collection.query(query_embeddings=[emb], n_results=2, include=["documents", "distances"])

def include_for_call(include: list[str], *, is_query: bool) -> list[str]:
    if not is_query:
        include = [i for i in include if i != "distances"]  # get() cannot return distances
    return include

res = collection.get(ids=ids, include=include_for_call(include, is_query=False))
res = collection.query(query_embeddings=[q], n_results=5, include=include_for_call(include, is_query=True))

def distances_allowed(method: str) -> bool:
    return method == "query"

def safe_include(include: list[str], method: str) -> bool:
    return "distances" not in include or distances_allowed(method)

try:
    res = collection.get(ids=ids, include=include)
except ValueError as e:
    if "Include item cannot be one of" in str(e) and "distances" in str(e):
        include = [i for i in include if i != "distances"]
        res = collection.get(ids=ids, include=include)
    else:
        raise

When it happens

Trigger: collection.get(ids=[...], include=["documents", "distances"]) or collection.get(where=..., include=["distances"]). Any shared include constant (e.g. IncludeMetadataDocumentsEmbeddingsDistances) reused for both query and get will trip this on the get path.

Common situations: Sharing one INCLUDE_WITH_DISTANCES constant between query() and get() code paths; refactoring a query into a get (by id) and keeping the old include list; assuming distances are computable for direct fetches.

Related errors

• Expected include to be a list, got {include}
• Expected include item to be a str, got {item}
• Expected include item to be one of {', '.join(valid_items)},
• Multiple embedding functions provided. Please provide only o
• Bad request to ${input} with status: ${resp.statusText}

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