chroma-core/chroma · error · ValueError

Sparse embedding function returned unexpected number of embe

Error message

Sparse embedding function returned unexpected number of embeddings

What it means

For a string Knn query against a schema key with an enabled sparse vector index, Chroma embeds `[query_text]` with the key's SparseEmbeddingFunction and requires exactly one sparse embedding back. The function returned an empty list or more than one embedding.

Source

Thrown at chromadb/api/models/CollectionCommon.py:884

            if sparse_index is not None and sparse_index.enabled:
                sparse_config = sparse_index.config
                if sparse_config.embedding_function is not None:
                    embedding_func = sparse_config.embedding_function
                    if not isinstance(embedding_func, SparseEmbeddingFunction):
                        embedding_func = cast(
                            SparseEmbeddingFunction[Any], embedding_func
                        )
                    validate_sparse_embedding_function(embedding_func)

                    # Embed the query
                    sparse_embedding = self._sparse_embed(
                        input=[query_text],
                        sparse_embedding_function=embedding_func,
                        is_query=True,
                    )

                    if not sparse_embedding or len(sparse_embedding) != 1:
                        raise ValueError(
                            "Sparse embedding function returned unexpected number of embeddings"
                        )

                    # Return a new Knn with the sparse embedding
                    return Knn(
                        query=sparse_embedding[0],
                        key=knn.key,
                        limit=knn.limit,
                        default=knn.default,
                        return_rank=knn.return_rank,
                    )

        # Check for dense vector with embedding function (float_list)
        if value_type.float_list is not None:
            vector_index = value_type.float_list.vector_index
            if vector_index is not None and vector_index.enabled:
                dense_config = vector_index.config
                if dense_config.embedding_function is not None:

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Ensure the sparse function's query path returns a list of exactly one SparseEmbedding for one input
2. Add `assert len(out) == len(input)` inside the wrapper to fail early at the source
3. Pass a precomputed sparse vector as the Knn query instead of a string

Example fix

# before
class MySparse:
    def embed_query(self, input):
        return self.__call__(input)  # returns wrong length for [text]

# after
class MySparse:
    def embed_query(self, input):
        out = self.__call__(input)
        assert len(out) == len(input)
        return out

probe = sparse_ef.embed_query(["test"]) if hasattr(sparse_ef, "embed_query") else sparse_ef(["test"])
assert len(probe) == 1

def checked_sparse_query_fn(fn):
    def wrapped(input):
        out = list(fn(input))
        assert len(out) == len(input), "sparse query embedding length mismatch"
        return out
    return wrapped

When it happens

Trigger: `Knn(query="text", key=<sparse-indexed key>, ...)` with a custom SparseEmbeddingFunction whose query embedding returns a wrong-length result for a single-item input.

Common situations: Sparse models wrapped so embed_query returns a matrix row, a generator, or a collapsed list; reusing a documents-oriented sparse function for queries without adapting the return shape.

Related errors

• Sparse embedding function returned unexpected number of embe
• Embedding function returned unexpected number of embeddings
• Failed to generate embeddings for your request.
• Updating '${key}' is not supported for ${NAME}
• HTTP ${response.status} ${response.statusText}: ${errorText}

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