chroma-core/chroma · error · ValueError

Cannot embed string query for key '{key}': key not found in

Error message

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

What it means

A Knn expression with a string query must target either the main embedding field or a key declared in the collection schema. This error fires when `key` is not present in `self.schema.keys`, so Chroma has no type information (dense vs sparse, embedding function) to embed the string with.

Source

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

            # Use the collection's main embedding function
            embedding = self._embed(input=[query_text], is_query=True)
            if not embedding or len(embedding) != 1:
                raise ValueError(
                    "Embedding function returned unexpected number of embeddings"
                )
            # Return a new Knn with the embedded query
            return Knn(
                query=embedding[0],
                key=knn.key,
                limit=knn.limit,
                default=knn.default,
                return_rank=knn.return_rank,
            )

        # Handle metadata field with potential sparse embedding
        schema = self.schema
        if schema is None or key not in schema.keys:
            raise ValueError(
                f"Cannot embed string query for key '{key}': "
                f"key not found in schema. Please provide an embedded vector or "
                f"configure an embedding function for this key in the schema."
            )

        value_type = schema.keys[key]

        # Check for sparse vector with embedding function
        if value_type.sparse_vector is not None:
            sparse_index = value_type.sparse_vector.sparse_vector_index
            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
                        )

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Declare the key in the collection schema with a vector index configuration at creation time
2. Fix the key name to match the schema exactly (check `collection.schema.keys`)
3. Use the main embedding field (default key) for plain text dense search, or query the field that actually exists

Example fix

# before
col.query(where=Knn(query="hello", key="title_vec", limit=5))  # key not in schema

# after
print(list(col.schema.keys))  # inspect real keys
col.query(where=Knn(query="hello", key="actual_key", limit=5))

schema_keys = set(collection.schema.keys) if collection.schema else set()
if knn_key not in schema_keys and knn_key != "embedding":
    raise ValueError(f"key {knn_key!r} not in schema; available: {sorted(schema_keys)}")

def is_known_knn_key(key: str, collection) -> bool:
    schema = collection.schema
    return schema is not None and key in schema.keys

When it happens

Trigger: `Knn(query="text", key="my_vector_field", ...)` where `my_vector_field` was never declared in the collection's schema — e.g. a typo, a renamed field, or querying a collection created without that key.

Common situations: Schema drift between environments (dev collection has the field, prod does not); copying a query from another project; misspelled key names.

Related errors

• Cannot embed string query for key '{key}': no embedding func
• Bad request to ${input} with status: ${resp.statusText}
• You must provide either queryEmbeddings or queryTexts
• Config validation failed for schema '${schemaName}': ${error
• Cannot enable all index types globally. Must specify either

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