{"record":{"id":"40c5d321ad19bcaa","repo":"chroma-core/chroma","slug":"sparsevector-indices-must-be-non-negative-got-id","errorCode":null,"errorMessage":"SparseVector indices must be non-negative, got {idx} at position {i}","messagePattern":"SparseVector indices must be non-negative, got (.+?) at position (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/base_types.py","lineNumber":67,"sourceCode":"\n        if self.labels is not None:\n            if not isinstance(self.labels, list):\n                raise ValueError(\n                    f\"Expected SparseVector labels to be a list, got {type(self.labels).__name__}\"\n                )\n            if len(self.labels) != len(self.indices):\n                raise ValueError(\n                    f\"SparseVector labels must have the same length as indices and values, \"\n                    f\"got {len(self.labels)} labels, {len(self.indices)} indices\"\n                )\n\n        for i, idx in enumerate(self.indices):\n            if not isinstance(idx, int):\n                raise ValueError(\n                    f\"SparseVector indices must be integers, got {type(idx).__name__} at position {i}\"\n                )\n            if idx < 0:\n                raise ValueError(\n                    f\"SparseVector indices must be non-negative, got {idx} at position {i}\"\n                )\n\n        for i, val in enumerate(self.values):\n            if not isinstance(val, (int, float)):\n                raise ValueError(\n                    f\"SparseVector values must be numbers, got {type(val).__name__} at position {i}\"\n                )\n\n        # Validate indices are sorted in strictly ascending order\n        if len(self.indices) > 1:\n            for i in range(1, len(self.indices)):\n                if self.indices[i] <= self.indices[i - 1]:\n                    raise ValueError(\n                        f\"SparseVector indices must be sorted in strictly ascending order, \"\n                        f\"found indices[{i}]={self.indices[i]} <= indices[{i-1}]={self.indices[i-1]}\"\n                    )\n","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/base_types.py#L49-L85","documentation":"SparseVector.__post_init__ enforces that every index is >= 0 because indices are positions in the collection's vector dimension space. A negative index has no meaning there, so construction fails immediately with the offending value and its position. This is a data-quality error in whatever produced the indices, not a Chroma configuration issue.","triggerScenarios":"Passing tokenizer/encoder IDs that use -1 as an OOV/padding sentinel; relative-position or offset math (i - window) that can go below zero; signed hash values (Python's hash() is signed) used directly as dimension indices.","commonSituations":"Sparse embeddings built from tokenizers that emit -1 for unknown tokens; feature-hashing pipelines where the hash can be negative; sliding-window features computed as differences and fed in unchecked.","solutions":["Filter out negative pairs before constructing, keeping indices and values aligned: pairs = [(i, v) for i, v in zip(indices, values) if i >= 0].","Fix the upstream producer to never emit -1 sentinel IDs (remap or drop them at the source).","If negatives mean 'missing', drop the entry entirely rather than clamping to 0, which would corrupt a real dimension."],"exampleFix":"// before\nsv = SparseVector(indices=[3, -1, 7], values=[0.2, 0.5, 0.1])  # ValueError: got -1 at position 1\n\n// after\npairs = [(i, v) for i, v in zip([3, -1, 7], [0.2, 0.5, 0.1]) if i >= 0]\nsv = SparseVector(indices=[i for i, _ in pairs], values=[v for _, v in pairs])","handlingStrategy":"validation","validationCode":"bad = [(pos, i) for pos, i in enumerate(indices) if i < 0]\nif bad:\n    # drop sentinel/invalid entries, keeping values aligned\n    pairs = [(i, v) for i, v in zip(indices, values) if i >= 0]\n    indices, values = [i for i, _ in pairs], [v for _, v in pairs]\nsv = SparseVector(indices=indices, values=values)","typeGuard":null,"tryCatchPattern":"try:\n    sv = SparseVector(indices=indices, values=values)\nexcept ValueError as e:\n    raise ValueError(f'encoder produced invalid indices for doc {doc_id}: {e}') from e","preventionTips":["Define your encoder's contract: indices are non-negative dimension IDs; map or drop -1 sentinels at the tokenizer boundary.","Never use signed hashes directly as indices - reduce modulo dimension count.","Property-test the sparse encoder with adversarial inputs (empty docs, all-OOV docs)."],"tags":["sparse-vector","index-validation","data-quality"],"backgroundTag":"sparse-vector-validation","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}