{"record":{"id":"6dff95370665d0b2","repo":"chroma-core/chroma","slug":"embedding-function-returned-unexpected-number-of-e-6dff95","errorCode":null,"errorMessage":"Embedding function returned unexpected number of embeddings","messagePattern":"Embedding function returned unexpected number of embeddings","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/models/CollectionCommon.py","lineNumber":840,"sourceCode":"        \"\"\"\n        from chromadb.execution.expression.operator import Knn\n\n        if not isinstance(knn, Knn):\n            return knn\n\n        # If query is not a string, nothing to do\n        if not isinstance(knn.query, str):\n            return knn\n\n        query_text = knn.query\n        key = knn.key\n\n        # Handle main embedding field\n        if key == EMBEDDING_KEY:\n            # Use the collection's main embedding function\n            embedding = self._embed(input=[query_text], is_query=True)\n            if not embedding or len(embedding) != 1:\n                raise ValueError(\n                    \"Embedding function returned unexpected number of embeddings\"\n                )\n            # Return a new Knn with the embedded query\n            return Knn(\n                query=embedding[0],\n                key=knn.key,\n                limit=knn.limit,\n                default=knn.default,\n                return_rank=knn.return_rank,\n            )\n\n        # Handle metadata field with potential sparse embedding\n        schema = self.schema\n        if schema is None or key not in schema.keys:\n            raise ValueError(\n                f\"Cannot embed string query for key '{key}': \"\n                f\"key not found in schema. Please provide an embedded vector or \"\n                f\"configure an embedding function for this key in the schema.\"","sourceCodeStart":822,"sourceCodeEnd":858,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/models/CollectionCommon.py#L822-L858","documentation":"For a Knn expression whose query is a plain string on the main embedding field, Chroma embeds `[query_text]` with the collection's embedding function and expects exactly one embedding back. A custom function returning zero results or more than one (or a bare vector instead of a length-1 list) triggers this error.","triggerScenarios":"`collection.query(where=Knn(query=\"some text\", key=\"embedding\", ...))` with a custom EmbeddingFunction whose embed_query/embed call returns the wrong shape for a single-item input list.","commonSituations":"Custom EFs that return a numpy array whose first dimension is not 1, that return a scalar embedding instead of a list, or that batch/collapse inputs internally.","solutions":["Make embed_query return a list of length equal to the input list — for one input, exactly one embedding","Wrap the EF to enforce the contract and get an early, clear failure: assert len(out) == len(input)","Pass a precomputed vector as the Knn query instead of a string"],"exampleFix":"# before\nclass MyEF:\n    def embed_query(self, input):\n        return self._model.encode(input)      # may return wrong shape/length\n\n# after\nclass MyEF:\n    def embed_query(self, input):\n        out = self._model.encode(input)\n        out = list(out)\n        assert len(out) == len(input)\n        return out","handlingStrategy":"type-guard","validationCode":"emb = collection._embedding_function.embed_query([\"probe\"])\nassert len(emb) == 1  # fails fast before the real query","typeGuard":"def checked_ef(ef):\n    def wrapped(input):\n        out = list(ef(input))\n        assert len(out) == len(input), f\"EF returned {len(out)} for {len(input)} inputs\"\n        return out\n    return wrapped","tryCatchPattern":null,"preventionTips":["Enforce input-length == output-length in every custom embedding function","Probe custom EFs once at startup with a single-string input","Prefer passing vectors for Knn queries when EF behavior is uncertain"],"tags":["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"}