chroma-core/chroma · error · ValueError

Expected include item to be a str, got {item}

Error message

Expected include item to be a str, got {item}

What it means

Each element of the include list must be a string. validate_include iterates the list and raises this ValueError on the first non-str item (int, None, dict, nested list).

Source

Thrown at chromadb/api/types.py:1343

        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:
    """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):

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. Filter/validate before the call: include = [i for i in include if isinstance(i, str)]
  2. Fix the code that appends non-string values into the include list
  3. Check for accidental nesting such as include=[["documents"]]

Example fix

# before
include = ["documents"] + [None if want_meta else "metadatas"]

# after
include = ["documents"]
if want_meta:
    include.append("metadatas")
Defensive patterns

Strategy: type-guard

Validate before calling

def clean_include(items):
    cleaned = [i for i in items if isinstance(i, str) and i]
    if not cleaned:
        raise ValueError("include list has no valid string items")
    return cleaned

res = collection.get(ids=ids, include=clean_include(raw_items))

Type guard

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

Try / catch

try:
    res = collection.query(query_embeddings=[q], include=include, n_results=5)
except ValueError as e:
    if "include item to be a str" in str(e):
        include = [i for i in include if isinstance(i, str)]
        res = collection.query(query_embeddings=[q], include=include, n_results=5)
    else:
        raise

Prevention

When it happens

Trigger: collection.query(..., include=["documents", None]) or include=["metadatas", 1] or a list built with a bug that appends indices/objects, e.g. include += [len(fields)].

Common situations: Optional fields appended as None placeholders; list built via zip/map that yields non-strings; deserialized JSON with mixed types; copy-paste leaving a stray comma creating nested lists.

Related errors

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