chroma-core/chroma · error · ValueError

SparseVector indices must be non-negative, got {idx} at posi

Error message

SparseVector indices must be non-negative, got {idx} at position {i}

What it means

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.

Source

Thrown at chromadb/base_types.py:67

        if self.labels is not None:
            if not isinstance(self.labels, list):
                raise ValueError(
                    f"Expected SparseVector labels to be a list, got {type(self.labels).__name__}"
                )
            if len(self.labels) != len(self.indices):
                raise ValueError(
                    f"SparseVector labels must have the same length as indices and values, "
                    f"got {len(self.labels)} labels, {len(self.indices)} indices"
                )

        for i, idx in enumerate(self.indices):
            if not isinstance(idx, int):
                raise ValueError(
                    f"SparseVector indices must be integers, got {type(idx).__name__} at position {i}"
                )
            if idx < 0:
                raise ValueError(
                    f"SparseVector indices must be non-negative, got {idx} at position {i}"
                )

        for i, val in enumerate(self.values):
            if not isinstance(val, (int, float)):
                raise ValueError(
                    f"SparseVector values must be numbers, got {type(val).__name__} at position {i}"
                )

        # Validate indices are sorted in strictly ascending order
        if len(self.indices) > 1:
            for i in range(1, len(self.indices)):
                if self.indices[i] <= self.indices[i - 1]:
                    raise ValueError(
                        f"SparseVector indices must be sorted in strictly ascending order, "
                        f"found indices[{i}]={self.indices[i]} <= indices[{i-1}]={self.indices[i-1]}"
                    )

View on GitHub (pinned to aecdd12c8a)

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.

Example fix

// before
sv = SparseVector(indices=[3, -1, 7], values=[0.2, 0.5, 0.1])  # ValueError: got -1 at position 1

// after
pairs = [(i, v) for i, v in zip([3, -1, 7], [0.2, 0.5, 0.1]) if i >= 0]
sv = SparseVector(indices=[i for i, _ in pairs], values=[v for _, v in pairs])

Defensive patterns

Strategy: validation

Validate before calling

bad = [(pos, i) for pos, i in enumerate(indices) if i < 0]
if bad:
    # drop sentinel/invalid entries, keeping values aligned
    pairs = [(i, v) for i, v in zip(indices, values) if i >= 0]
    indices, values = [i for i, _ in pairs], [v for _, v in pairs]
sv = SparseVector(indices=indices, values=values)

Try / catch

try:
    sv = SparseVector(indices=indices, values=values)
except ValueError as e:
    raise ValueError(f'encoder produced invalid indices for doc {doc_id}: {e}') from e

Prevention

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).

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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