{"record":{"id":"a00839113562b91a","repo":"chroma-core/chroma","slug":"invalid-legacy-hnsw-parameter-name-name","errorCode":null,"errorMessage":"Invalid legacy HNSW parameter name: {name}","messagePattern":"Invalid legacy HNSW parameter name: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/configuration.py","lineNumber":311,"sourceCode":"\n        # We maintain this map to avoid a circular import with HnswParams, and\n        # because then names won't change since we intend to deprecate HNSWParams\n        # in favor of this type of configuration.\n        old_to_new = {\n            \"hnsw:space\": \"space\",\n            \"hnsw:construction_ef\": \"ef_construction\",\n            \"hnsw:search_ef\": \"ef_search\",\n            \"hnsw:M\": \"M\",\n            \"hnsw:num_threads\": \"num_threads\",\n            \"hnsw:resize_factor\": \"resize_factor\",\n            \"hnsw:batch_size\": \"batch_size\",\n            \"hnsw:sync_threshold\": \"sync_threshold\",\n        }\n\n        parameters = []\n        for name, value in params.items():\n            if name not in old_to_new:\n                raise ValueError(f\"Invalid legacy HNSW parameter name: {name}\")\n            parameters.append(\n                ConfigurationParameter(name=old_to_new[name], value=value)\n            )\n        return cls(parameters)\n\n\n# This is the user-facing interface for HNSW index configuration parameters.\n# Internally, we pass around HNSWConfigurationInternal objects, which perform\n# validation, serialization and deserialization. Users don't need to know\n# about that and instead get a clean constructor with default arguments.\nclass HNSWConfigurationInterface(HNSWConfigurationInternal):\n    \"\"\"HNSW index configuration parameters.\n    See https://docs.trychroma.com/guides#changing-the-distance-function for more information.\n    \"\"\"\n\n    def __init__(\n        self,\n        space: str = \"l2\",","sourceCodeStart":293,"sourceCodeEnd":329,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/configuration.py#L293-L329","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Filter the dict to the known legacy keys before migrating (see the old_to_new map in the source)","Strip application metadata from the dict first and keep only the exact hnsw: keys you intend to migrate","Fix typos and casing so keys match the documented legacy names exactly"],"exampleFix":"# before\nlegacy = {\"hnsw:space\": \"cosine\", \"app:tenant\": \"acme\"}\ncfg = HNSWConfigurationInternal.from_legacy_params(legacy)   # unknown key\n# after\nlegacy_hnsw = {k: v for k, v in legacy.items() if k.startswith(\"hnsw:\")}\ncfg = HNSWConfigurationInternal.from_legacy_params(legacy_hnsw)","handlingStrategy":"validation","validationCode":"KNOWN_LEGACY_HNSW = {\n    \"hnsw:space\", \"hnsw:construction_ef\", \"hnsw:search_ef\", \"hnsw:M\",\n    \"hnsw:num_threads\", \"hnsw:resize_factor\", \"hnsw:batch_size\", \"hnsw:sync_threshold\",\n}\n\ndef legacy_hnsw_only(metadata: dict) -> dict:\n    return {k: v for k, v in metadata.items() if k in KNOWN_LEGACY_HNSW}\n\ncfg = HNSWConfigurationInternal.from_legacy_params(legacy_hnsw_only(collection_metadata))","typeGuard":null,"tryCatchPattern":"try:\n    cfg = HNSWConfigurationInternal.from_legacy_params(metadata)\nexcept ValueError as e:\n    if \"Invalid legacy HNSW parameter name\" in str(e):\n        cfg = HNSWConfigurationInternal.from_legacy_params(legacy_hnsw_only(metadata))\n    else:\n        raise","preventionTips":["Filter collection metadata down to the exact known hnsw: keys before migrating","Keep application data out of the metadata dict you feed to from_legacy_params","Watch for typos and casing in legacy prefixed keys; they must match exactly"],"tags":["chromadb","configuration","hnsw","legacy-migration","metadata"],"backgroundTag":"configuration-validation-failed","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}