chroma-core/chroma · info · ValueError

not a valid spann config: {e}

Error message

not a valid spann config: {e}

What it means

Companion dead branch in collection_configuration_to_json(): the 'spann' value is passed through typing.cast(SpannConfiguration, ...) with an except that would raise this ValueError. Since typing.cast performs no runtime validation, the exception can never fire; the branch exists only as (ineffective) intent to reject invalid SPANN configuration dicts.

Source

Thrown at chromadb/api/collection_configuration.py:151

            spann_config = config.get_parameter("spann").value
        except ValueError:
            spann_config = None
        try:
            ef = config.get_parameter("embedding_function").value
        except ValueError:
            ef = None

    ef_config: Dict[str, Any] | None = None
    if hnsw_config is not None:
        try:
            hnsw_config = cast(HNSWConfiguration, hnsw_config)
        except Exception as e:
            raise ValueError(f"not a valid hnsw config: {e}")
    if spann_config is not None:
        try:
            spann_config = cast(SpannConfiguration, spann_config)
        except Exception as e:
            raise ValueError(f"not a valid spann config: {e}")

    if ef is None:
        ef = None
        ef_config = {"type": "legacy"}

    if ef is not None:
        try:
            if ef.is_legacy():
                ef_config = {"type": "legacy"}
            else:
                ef_config = {
                    "name": ef.name(),
                    "type": "known",
                    "config": ef.get_config(),
                }
                register_embedding_function(type(ef))  # type: ignore
        except Exception as e:
            warnings.warn(

View on GitHub (pinned to aecdd12c8a)

Solutions

1. No action needed — unreachable code.
2. For genuine SPANN validation, check the dict keys against SpannConfiguration fields before passing the configuration in.

SPANN_KEYS = {"search_nprobe", "write_nprobe", "space", "ef_construction", "ef_search", "max_neighbors", "reassign_neighbor_count", "split_threshold", "merge_threshold"}

def valid_spann_dict(cfg: dict) -> bool:
    return isinstance(cfg, dict) and set(cfg) <= SPANN_KEYS

When it happens

Trigger: None at runtime — the cast never raises, so this error is unreachable as written.

Common situations: Found only via source search or code review; no user-visible behavior is attached to it.

Related errors

• hnsw and spann cannot both be provided
• not a valid hnsw config: {e}
• Vector index cannot be enabled on specific keys. Use createI
• Deleting vector index is not currently supported.
• Embedding function name not found in config: {ef_config}

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