{"record":{"id":"23729f571ee02ec5","repo":"chroma-core/chroma","slug":"expected-sparsevector-instance-at-position-i-go","errorCode":null,"errorMessage":"Expected SparseVector instance at position {i}, got {type(vector).__name__}","messagePattern":"Expected SparseVector instance at position (.+?), got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/types.py","lineNumber":1434,"sourceCode":"    - Vectors is a list\n    - List is non-empty\n    - All items are SparseVector instances\n\n    Note: Individual SparseVector validation (sorted indices, non-negative values, etc.)\n    happens automatically in SparseVector.__post_init__ when each instance is created.\n    This function only validates the list structure and instance types.\n    \"\"\"\n    if not isinstance(vectors, list):\n        raise ValueError(\n            f\"Expected sparse vectors to be a list, got {type(vectors).__name__}\"\n        )\n    if len(vectors) == 0:\n        raise ValueError(\n            f\"Expected sparse vectors to be a non-empty list, got {len(vectors)} sparse vectors\"\n        )\n    for i, vector in enumerate(vectors):\n        if not isinstance(vector, SparseVector):\n            raise ValueError(\n                f\"Expected SparseVector instance at position {i}, got {type(vector).__name__}\"\n            )\n    return vectors\n\n\ndef validate_documents(documents: Documents, nullable: bool = False) -> None:\n    \"\"\"Validates documents to ensure it is a list of strings\"\"\"\n    if not isinstance(documents, list):\n        raise ValueError(\n            f\"Expected documents to be a list, got {type(documents).__name__}\"\n        )\n    if len(documents) == 0:\n        raise ValueError(\n            f\"Expected documents to be a non-empty list, got {len(documents)} documents\"\n        )\n    for document in documents:\n        # If embeddings are present, some documents can be None\n        if document is None and nullable:","sourceCodeStart":1416,"sourceCodeEnd":1452,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/types.py#L1416-L1452","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nsparse_vectors = [{\"indices\": [0, 5], \"values\": [0.1, 0.2]}]\n\n# after\nfrom chromadb.api.types import SparseVector\nsparse_vectors = [SparseVector(indices=[0, 5], values=[0.1, 0.2])]","handlingStrategy":"type-guard","validationCode":"from chromadb.api.types import SparseVector\n\ndef rehydrate_sparse(vectors):\n    \"\"\"Convert dicts/tuples (e.g. from JSON) into SparseVector instances.\"\"\"\n    out = []\n    for i, v in enumerate(vectors):\n        if isinstance(v, SparseVector):\n            out.append(v)\n        elif isinstance(v, dict):\n            out.append(SparseVector(indices=v[\"indices\"], values=v[\"values\"]))\n        else:\n            raise TypeError(f\"sparse vector at {i} is {type(v).__name__}, expected SparseVector or dict\")\n    return out","typeGuard":"from chromadb.api.types import SparseVector\n\ndef all_sparse_instances(vectors) -> bool:\n    return all(isinstance(v, SparseVector) for v in vectors)","tryCatchPattern":"try:\n    collection.add(ids=ids, sparse_vectors=sv, documents=docs)\nexcept ValueError as e:\n    if \"Expected SparseVector instance\" in str(e):\n        sv = [SparseVector(**v) if isinstance(v, dict) else v for v in sv]\n        collection.add(ids=ids, sparse_vectors=sv, documents=docs)\n    else:\n        raise","preventionTips":["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"],"tags":["chromadb","sparse-vectors","type-mismatch","isinstance"],"backgroundTag":"sparse-vector-validation","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}