chroma-core/chroma · error · ValueError

Expected SparseVector instance at position {i}, got {type(ve

Error message

Expected SparseVector instance at position {i}, got {type(vector).__name__}

What it means

Every element of the sparse vector list must be a chromadb.api.types.SparseVector instance. validate_sparse_vectors checks isinstance per position and reports the position i and the offending type name. Plain dicts ({"indices": ..., "values": ...}), tuples, or lists are not accepted.

Source

Thrown at chromadb/api/types.py:1434

    - Vectors is a list
    - List is non-empty
    - All items are SparseVector instances

    Note: Individual SparseVector validation (sorted indices, non-negative values, etc.)
    happens automatically in SparseVector.__post_init__ when each instance is created.
    This function only validates the list structure and instance types.
    """
    if not isinstance(vectors, list):
        raise ValueError(
            f"Expected sparse vectors to be a list, got {type(vectors).__name__}"
        )
    if len(vectors) == 0:
        raise ValueError(
            f"Expected sparse vectors to be a non-empty list, got {len(vectors)} sparse vectors"
        )
    for i, vector in enumerate(vectors):
        if not isinstance(vector, SparseVector):
            raise ValueError(
                f"Expected SparseVector instance at position {i}, got {type(vector).__name__}"
            )
    return vectors


def validate_documents(documents: Documents, nullable: bool = False) -> None:
    """Validates documents to ensure it is a list of strings"""
    if not isinstance(documents, list):
        raise ValueError(
            f"Expected documents to be a list, got {type(documents).__name__}"
        )
    if len(documents) == 0:
        raise ValueError(
            f"Expected documents to be a non-empty list, got {len(documents)} documents"
        )
    for document in documents:
        # If embeddings are present, some documents can be None
        if document is None and nullable:

View on GitHub (pinned to aecdd12c8a)

Solutions

Construct real instances: SparseVector(indices=[0, 5], values=[0.1, 0.2])
If data came from JSON, rehydrate: [SparseVector(**d) for d in dicts]
Check pip list / pip show chromadb for duplicate installs and consolidate to one import path

Example fix

# before
sparse_vectors = [{"indices": [0, 5], "values": [0.1, 0.2]}]

# after
from chromadb.api.types import SparseVector
sparse_vectors = [SparseVector(indices=[0, 5], values=[0.1, 0.2])]

Defensive patterns

Strategy: type-guard

Validate before calling

from chromadb.api.types import SparseVector

def rehydrate_sparse(vectors):
    """Convert dicts/tuples (e.g. from JSON) into SparseVector instances."""
    out = []
    for i, v in enumerate(vectors):
        if isinstance(v, SparseVector):
            out.append(v)
        elif isinstance(v, dict):
            out.append(SparseVector(indices=v["indices"], values=v["values"]))
        else:
            raise TypeError(f"sparse vector at {i} is {type(v).__name__}, expected SparseVector or dict")
    return out

Type guard

from chromadb.api.types import SparseVector

def all_sparse_instances(vectors) -> bool:
    return all(isinstance(v, SparseVector) for v in vectors)

Try / catch

try:
    collection.add(ids=ids, sparse_vectors=sv, documents=docs)
except ValueError as e:
    if "Expected SparseVector instance" in str(e):
        sv = [SparseVector(**v) if isinstance(v, dict) else v for v in sv]
        collection.add(ids=ids, sparse_vectors=sv, documents=docs)
    else:
        raise

Prevention

Always construct SparseVector(indices=..., values=...) — dict/tuple forms are not accepted
Rehydrate sparse vectors after JSON round-trips
Check for duplicate chromadb installs (pip show -f chromadb) if isinstance inexplicably fails — two module copies means two classes

When it happens

Trigger: Passing sparse_vectors=[{"indices": [0, 5], "values": [0.1, 0.2]}] (dict form); a custom EF returning (indices, values) tuples; a SparseVector imported from a duplicated chromadb install/module copy, which fails isinstance across module identities.

Common situations: Serializing sparse vectors to JSON and back (they become dicts); dual chromadb installs (pip + local checkout) creating two SparseVector classes; hand-building inputs from the REST API shapes instead of the Python types.

Related errors

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