chroma-core/chroma · info · ValueError

not a valid hnsw config: {e}

Error message

not a valid hnsw config: {e}

What it means

In collection_configuration_to_json(), the value stored under 'hnsw' is passed through typing.cast(HNSWConfiguration, ...) inside a try/except that would raise this ValueError. typing.cast is a runtime no-op that never raises, so this except branch is unreachable in the current code — the error cannot actually be thrown. Its intent was to reject an hnsw configuration that is not a valid HNSW configuration dict.

Source

Thrown at chromadb/api/collection_configuration.py:146

        try:
            hnsw_config = config.get_parameter("hnsw").value
        except ValueError:
            hnsw_config = None
        try:
            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",

View on GitHub (pinned to aecdd12c8a)

Solutions

1. No action needed — the branch is dead code and cannot raise.
2. If you maintain a fork and want real enforcement, validate the dict's keys against CreateHNSWConfiguration fields yourself before serializing.

HNSW_KEYS = {"space", "ef_construction", "max_neighbors", "ef_search", "num_threads", "batch_size", "sync_threshold", "resize_factor"}

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

When it happens

Trigger: None at runtime — typing.cast never raises, so the except never fires. It would only matter if a fork replaced the cast with real validation.

Common situations: Developers encounter this string while grepping sources or in static analysis and assume hnsw config validation happens here; in reality malformed hnsw dicts are not caught by this branch.

Related errors

• hnsw and spann cannot both be provided
• not a valid spann 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/131cdea0935b6c82. Report an issue: GitHub.