chroma-core/chroma · error · ValueError

Invalid legacy HNSW parameter name: {name}

Error message

Invalid legacy HNSW parameter name: {name}

What it means

HNSWConfigurationInternal.from_legacy_params (chromadb/api/configuration.py:311) raises this ValueError when migrating a legacy metadata dict whose keys are not exactly the known prefixed HNSW names (hnsw:space, hnsw:construction_ef, hnsw:search_ef, hnsw:M, hnsw:num_threads, hnsw:resize_factor, hnsw:batch_size, hnsw:sync_threshold). The migration helper maps old names to new ones strictly; any other key - a typo, an unknown hnsw: variant, or plain non-HNSW metadata mixed into the dict - is rejected.

Source

Thrown at chromadb/api/configuration.py:311

        # We maintain this map to avoid a circular import with HnswParams, and
        # because then names won't change since we intend to deprecate HNSWParams
        # in favor of this type of configuration.
        old_to_new = {
            "hnsw:space": "space",
            "hnsw:construction_ef": "ef_construction",
            "hnsw:search_ef": "ef_search",
            "hnsw:M": "M",
            "hnsw:num_threads": "num_threads",
            "hnsw:resize_factor": "resize_factor",
            "hnsw:batch_size": "batch_size",
            "hnsw:sync_threshold": "sync_threshold",
        }

        parameters = []
        for name, value in params.items():
            if name not in old_to_new:
                raise ValueError(f"Invalid legacy HNSW parameter name: {name}")
            parameters.append(
                ConfigurationParameter(name=old_to_new[name], value=value)
            )
        return cls(parameters)


# This is the user-facing interface for HNSW index configuration parameters.
# Internally, we pass around HNSWConfigurationInternal objects, which perform
# validation, serialization and deserialization. Users don't need to know
# about that and instead get a clean constructor with default arguments.
class HNSWConfigurationInterface(HNSWConfigurationInternal):
    """HNSW index configuration parameters.
    See https://docs.trychroma.com/guides#changing-the-distance-function for more information.
    """

    def __init__(
        self,
        space: str = "l2",

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Filter the dict to the known legacy keys before migrating (see the old_to_new map in the source)
2. Strip application metadata from the dict first and keep only the exact hnsw: keys you intend to migrate
3. Fix typos and casing so keys match the documented legacy names exactly

Example fix

# before
legacy = {"hnsw:space": "cosine", "app:tenant": "acme"}
cfg = HNSWConfigurationInternal.from_legacy_params(legacy)   # unknown key
# after
legacy_hnsw = {k: v for k, v in legacy.items() if k.startswith("hnsw:")}
cfg = HNSWConfigurationInternal.from_legacy_params(legacy_hnsw)

KNOWN_LEGACY_HNSW = {
    "hnsw:space", "hnsw:construction_ef", "hnsw:search_ef", "hnsw:M",
    "hnsw:num_threads", "hnsw:resize_factor", "hnsw:batch_size", "hnsw:sync_threshold",
}

def legacy_hnsw_only(metadata: dict) -> dict:
    return {k: v for k, v in metadata.items() if k in KNOWN_LEGACY_HNSW}

cfg = HNSWConfigurationInternal.from_legacy_params(legacy_hnsw_only(collection_metadata))

try:
    cfg = HNSWConfigurationInternal.from_legacy_params(metadata)
except ValueError as e:
    if "Invalid legacy HNSW parameter name" in str(e):
        cfg = HNSWConfigurationInternal.from_legacy_params(legacy_hnsw_only(metadata))
    else:
        raise

When it happens

Trigger: Passing a collection's entire metadata dict that also contains application keys (e.g. {"hnsw:space": "cosine", "app:tenant": "acme"}); a legacy key with a typo like "hnsw:search-ef" or an unsupported experimental key like "hnsw:ef"; whitespace or case differences in the prefixed key.

Common situations: Bulk-migrating old collections whose metadata was used for both index tuning and app data; hand-edited metadata with near-miss key names; legacy metadata written by forks or plugins that added extra hnsw: keys.

Related errors

• Cannot set static parameter: {name}
• batch_size must be less than or equal to sync_threshold
• Cannot specify both 'hnsw' and 'spann' configurations during
• Invalid HNSW config provided in CreateCollectionConfiguratio
• Cannot specify both 'hnsw' and 'spann' configurations during

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