{"record":{"id":"50c40f2171cd45f3","repo":"chroma-core/chroma","slug":"sparse-embedding-function-returned-unexpected-numb-50c40f","errorCode":null,"errorMessage":"Sparse embedding function returned unexpected number of embeddings","messagePattern":"Sparse embedding function returned unexpected number of embeddings","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/models/CollectionCommon.py","lineNumber":884,"sourceCode":"            if sparse_index is not None and sparse_index.enabled:\n                sparse_config = sparse_index.config\n                if sparse_config.embedding_function is not None:\n                    embedding_func = sparse_config.embedding_function\n                    if not isinstance(embedding_func, SparseEmbeddingFunction):\n                        embedding_func = cast(\n                            SparseEmbeddingFunction[Any], embedding_func\n                        )\n                    validate_sparse_embedding_function(embedding_func)\n\n                    # Embed the query\n                    sparse_embedding = self._sparse_embed(\n                        input=[query_text],\n                        sparse_embedding_function=embedding_func,\n                        is_query=True,\n                    )\n\n                    if not sparse_embedding or len(sparse_embedding) != 1:\n                        raise ValueError(\n                            \"Sparse embedding function returned unexpected number of embeddings\"\n                        )\n\n                    # Return a new Knn with the sparse embedding\n                    return Knn(\n                        query=sparse_embedding[0],\n                        key=knn.key,\n                        limit=knn.limit,\n                        default=knn.default,\n                        return_rank=knn.return_rank,\n                    )\n\n        # Check for dense vector with embedding function (float_list)\n        if value_type.float_list is not None:\n            vector_index = value_type.float_list.vector_index\n            if vector_index is not None and vector_index.enabled:\n                dense_config = vector_index.config\n                if dense_config.embedding_function is not None:","sourceCodeStart":866,"sourceCodeEnd":902,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/models/CollectionCommon.py#L866-L902","documentation":"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.","triggerScenarios":"`Knn(query=\"text\", key=<sparse-indexed key>, ...)` with a custom SparseEmbeddingFunction whose query embedding returns a wrong-length result for a single-item input.","commonSituations":"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.","solutions":["Ensure the sparse function's query path returns a list of exactly one SparseEmbedding for one input","Add `assert len(out) == len(input)` inside the wrapper to fail early at the source","Pass a precomputed sparse vector as the Knn query instead of a string"],"exampleFix":"# before\nclass MySparse:\n    def embed_query(self, input):\n        return self.__call__(input)  # returns wrong length for [text]\n\n# after\nclass MySparse:\n    def embed_query(self, input):\n        out = self.__call__(input)\n        assert len(out) == len(input)\n        return out","handlingStrategy":"type-guard","validationCode":"probe = sparse_ef.embed_query([\"test\"]) if hasattr(sparse_ef, \"embed_query\") else sparse_ef([\"test\"])\nassert len(probe) == 1","typeGuard":"def checked_sparse_query_fn(fn):\n    def wrapped(input):\n        out = list(fn(input))\n        assert len(out) == len(input), \"sparse query embedding length mismatch\"\n        return out\n    return wrapped","tryCatchPattern":null,"preventionTips":["Verify sparse query paths (embed_query and __call__) return 1:1 with input","Smoke-test every schema-configured sparse function at app startup","Pass precomputed sparse vectors when the query path cannot be trusted"],"tags":["sparse-embeddings","knn-query","custom-embedding-function","count-mismatch"],"backgroundTag":"embedding-count-mismatch","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}