chroma-core/chroma · error · ValueError

Schema is missing keys[{embedding_key}]

Error message

Schema is missing keys[{embedding_key}]

What it means

This ValueError from update_schema_from_collection_configuration is raised when applying a configuration update to a Schema that has no '#embedding' key. The #embedding key is the well-known name for the column holding vector embeddings; without it there is nothing to attach index updates to, so the modify is rejected. It typically signals a schema built without embeddings support or a malformed/custom schema.

Source

Thrown at chromadb/api/collection_configuration.py:836

    Args:
        schema: The existing Schema object
        configuration: The configuration updates to apply

    Returns:
        Updated Schema object
    """

    # Get the vector index from defaults and #embedding key
    if (
        schema.defaults.float_list is None
        or schema.defaults.float_list.vector_index is None
    ):
        raise ValueError("Schema is missing defaults.float_list.vector_index")

    embedding_key = "#embedding"
    if embedding_key not in schema.keys:
        raise ValueError(f"Schema is missing keys[{embedding_key}]")

    embedding_value_types = schema.keys[embedding_key]
    if (
        embedding_value_types.float_list is None
        or embedding_value_types.float_list.vector_index is None
    ):
        raise ValueError(
            f"Schema is missing keys[{embedding_key}].float_list.vector_index"
        )

    # Update vector index config in both locations
    for vector_index in [
        schema.defaults.float_list.vector_index,
        embedding_value_types.float_list.vector_index,
    ]:
        if "hnsw" in configuration and configuration["hnsw"] is not None:
            # Update HNSW config
            if vector_index.config.hnsw is None:

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Only call modify with index/embedding updates on collections that actually contain embeddings (verify '#embedding' is in the schema keys via collection introspection)
2. Recreate the collection with a proper embedding configuration and re-ingest if the schema is permanently malformed
3. Upgrade client and server to matching current versions before modifying legacy collections

def collection_likely_has_embeddings(collection) -> bool:
    try:
        peek = collection.get(limit=1, include=['embeddings'])
        return bool(peek['ids'])
    except Exception:
        return False

if collection_likely_has_embeddings(collection):
    collection.modify(configuration=update)

try:
    collection.modify(configuration=update)
except ValueError as e:
    if 'Schema is missing keys[#embedding]' in str(e):
        # recreate collection with a full configuration and re-ingest
        migrate_to_new_collection(collection)
    else:
        raise

When it happens

Trigger: Calling client.modify_collection/collection.modify with an hnsw/spann (or embedding-function) update on a collection whose Schema.keys does not contain '#embedding' — for instance a collection created only for metadata/full-text storage, restored from an incompatible older version, or a schema assembled by hand in tests.

Common situations: Modifying collections that were created without embedding data or with very old Chroma versions lacking the #embedding convention; custom server builds; data restored from a dump with a lossy schema.

Related errors

• Schema is missing defaults.float_list.vector_index
• Schema is missing keys[{embedding_key}].float_list.vector_in
• Cannot enable all index types globally. Must specify either
• Cannot create index on special key '${key}'. This key is man
• Cannot create index on special key '${key}' with this config

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