chroma-core/chroma · error · ValueError

Cannot embed string query for key '{key}': no embedding func

Error message

Cannot embed string query for key '{key}': no embedding function configured for this key in the schema. Please provide an embedded vector or configure an embedding function.

What it means

The Knn query targets a key that exists in the schema, but that key's dense vector index has no embedding_function configured (dense_config.embedding_function is None and no sparse path matched). Chroma cannot turn the string query into a vector, so it tells you to send a vector or configure the function.

Source

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

                    except AttributeError:
                        # Fallback if embed_query doesn't exist
                        embeddings = embedding_func([query_text])

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

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

        raise ValueError(
            f"Cannot embed string query for key '{key}': "
            f"no embedding function configured for this key in the schema. "
            f"Please provide an embedded vector or configure an embedding function."
        )

    def _embed_rank_string_queries(self, rank: Any) -> Any:
        """Recursively embed string queries in Rank expressions.

        Args:
            rank: A Rank expression that may contain Knn objects with string queries

        Returns:
            A Rank expression with all string queries embedded
        """
        # Import here to avoid circular dependency
        from chromadb.execution.expression.operator import (
            Knn,
            Abs,

View on GitHub (pinned to aecdd12c8a)

Solutions

Configure an embedding function on that key's dense vector index in the collection schema
Embed the string yourself and pass the resulting vector as the Knn query
Use a key that does have an embedding function, or the main embedding field

Example fix

# before
col.query(where=Knn(query="hello", key="body_vec", limit=5))  # no EF on body_vec

# after
vec = my_embedder.embed_query("hello")
col.query(where=Knn(query=vec, key="body_vec", limit=5))  # pass the vector

Defensive patterns

Strategy: validation

Validate before calling

key_conf = collection.schema.keys.get(knn_key)
dense_ef = (key_conf.float_list.vector_index.config.embedding_function
            if key_conf and key_conf.float_list and key_conf.float_list.vector_index else None)
if isinstance(knn_query, str) and dense_ef is None:
    knn_query = my_embedder.embed_query(knn_query)  # embed it yourself

Type guard

def key_has_embedding_function(collection, key: str) -> bool:
    schema = collection.schema
    if schema is None or key not in schema.keys:
        return False
    kt = schema.keys[key]
    dense = getattr(kt, "float_list", None)
    cfg = getattr(getattr(dense, "vector_index", None), "config", None)
    return getattr(cfg, "embedding_function", None) is not None

Prevention

Configure an embedding function on every schema key you intend to query with strings
For externally-embedded collections, always embed queries client-side and pass vectors
Add a startup check listing schema keys lacking an embedding function

When it happens

Trigger: `Knn(query="text", key=<schema key>, ...)` where the key was declared with a float vector index but created without an embedding function in its config, and the collection has no usable fallback for that key.

Common situations: Collections built for precomputed-external embeddings (e.g. OpenAI vectors stored directly) later queried with raw strings; partial schema configs where only index type was set.

Related errors

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