chroma-core/chroma · error · ValueError

Trying to update HNSW config but schema has SPANN

Error message

Trying to update HNSW config but schema has SPANN

What it means

This ValueError inside update_schema_from_collection_configuration is raised when an update payload contains an hnsw block but the collection's vector_index.config.hnsw is None — meaning the collection was created with the SPANN index (or has no HNSW index). Chroma does not convert a SPANN collection to HNSW via modify; the update must match the index type already in the schema.

Source

Thrown at chromadb/api/collection_configuration.py:855

    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:
                raise ValueError("Trying to update HNSW config but schema has SPANN")

            hnsw_config = vector_index.config.hnsw
            update_hnsw = configuration["hnsw"]

            # Only update fields that are present in the update
            if "ef_search" in update_hnsw:
                hnsw_config.ef_search = update_hnsw["ef_search"]
            if "num_threads" in update_hnsw:
                hnsw_config.num_threads = update_hnsw["num_threads"]
            if "batch_size" in update_hnsw:
                hnsw_config.batch_size = update_hnsw["batch_size"]
            if "sync_threshold" in update_hnsw:
                hnsw_config.sync_threshold = update_hnsw["sync_threshold"]
            if "resize_factor" in update_hnsw:
                hnsw_config.resize_factor = update_hnsw["resize_factor"]

        elif "spann" in configuration and configuration["spann"] is not None:
            # Update SPANN config

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Check which index type the collection uses (configuration/metadata) and send the matching block ('spann' updates for SPANN collections)
2. To move a SPANN collection to HNSW, create a new collection with an hnsw configuration and re-ingest the embeddings
3. Keep per-collection config templates keyed by index type to avoid cross-applied payloads

Example fix

// before
# collection created with configuration={'spann': {'search_nprobe': 8}}
collection.modify(configuration={'hnsw': {'ef_search': 100}})  # ValueError

// after
collection.modify(configuration={'spann': {'search_nprobe': 16, 'ef_search': 100}})

def index_type_of(collection) -> str:
    cfg = collection.configuration or {}
    return 'spann' if cfg.get('spann') is not None else 'hnsw'

update = {index_type_of(collection): {'ef_search': 100}}
collection.modify(configuration=update)

def update_matches_index(update: dict, collection) -> bool:
    cfg = collection.configuration or {}
    if update.get('hnsw') is not None:
        return cfg.get('hnsw') is not None
    if update.get('spann') is not None:
        return cfg.get('spann') is not None
    return True

try:
    collection.modify(configuration=update)
except ValueError as e:
    if 'Trying to update HNSW config but schema has SPANN' in str(e):
        collection.modify(configuration={'spann': {'ef_search': update['hnsw']['ef_search']}})
    else:
        raise

When it happens

Trigger: Creating a collection with configuration={'spann': {...}} and then calling collection.modify(configuration={'hnsw': {'ef_search': 100}}). The check runs for both copies of the vector index (defaults and '#embedding' key) and raises as soon as the first lacks hnsw.

Common situations: Teams tuning HNSW knobs against a collection that was actually provisioned with SPANN; config templates reused across collections with different index types; assuming modify can switch index types in place.

Related errors

• Trying to update SPANN config but schema has HNSW
• hnsw and spann cannot both be provided
• Cannot specify both 'hnsw' and 'spann' configurations during
• Cannot specify both 'hnsw' and 'spann' configurations during
• not a valid hnsw config: {e}

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