{"record":{"id":"5230d3731fcc5fdb","repo":"chroma-core/chroma","slug":"cannot-embed-string-query-for-key-key-key-not","errorCode":null,"errorMessage":"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.","messagePattern":"Cannot embed string query for key '(.+?)': key not found in schema\\. Please provide an embedded vector or configure an embedding function for this key in the schema\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/models/CollectionCommon.py","lineNumber":855,"sourceCode":"            # 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.\"\n            )\n\n        value_type = schema.keys[key]\n\n        # Check for sparse vector with embedding function\n        if value_type.sparse_vector is not None:\n            sparse_index = value_type.sparse_vector.sparse_vector_index\n            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                        )","sourceCodeStart":837,"sourceCodeEnd":873,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/models/CollectionCommon.py#L837-L873","documentation":"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.","triggerScenarios":"`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.","commonSituations":"Schema drift between environments (dev collection has the field, prod does not); copying a query from another project; misspelled key names.","solutions":["Declare the key in the collection schema with a vector index configuration at creation time","Fix the key name to match the schema exactly (check `collection.schema.keys`)","Use the main embedding field (default key) for plain text dense search, or query the field that actually exists"],"exampleFix":"# before\ncol.query(where=Knn(query=\"hello\", key=\"title_vec\", limit=5))  # key not in schema\n\n# after\nprint(list(col.schema.keys))  # inspect real keys\ncol.query(where=Knn(query=\"hello\", key=\"actual_key\", limit=5))","handlingStrategy":"validation","validationCode":"schema_keys = set(collection.schema.keys) if collection.schema else set()\nif knn_key not in schema_keys and knn_key != \"embedding\":\n    raise ValueError(f\"key {knn_key!r} not in schema; available: {sorted(schema_keys)}\")","typeGuard":"def is_known_knn_key(key: str, collection) -> bool:\n    schema = collection.schema\n    return schema is not None and key in schema.keys","tryCatchPattern":null,"preventionTips":["Derive Knn key names from collection.schema.keys instead of hardcoding","Fail fast at startup if expected schema keys are missing (schema drift check)","Use the main embedding field for plain-text dense queries"],"tags":["schema","knn-query","vector-search","key-not-found"],"backgroundTag":"schema-key-not-found","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}