{"record":{"id":"3c69bded45b834de","repo":"chroma-core/chroma","slug":"not-a-valid-space-space-value","errorCode":null,"errorMessage":"not a valid space: {space_value}","messagePattern":"not a valid space: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/collection_configuration.py","lineNumber":204,"sourceCode":"    ef_construction: int\n    max_neighbors: int\n    ef_search: int\n    num_threads: int\n    batch_size: int\n    sync_threshold: int\n    resize_factor: float\n\n\ndef json_to_create_hnsw_configuration(\n    json_map: Dict[str, Any]\n) -> CreateHNSWConfiguration:\n    config: CreateHNSWConfiguration = {}\n    if \"space\" in json_map:\n        space_value = json_map[\"space\"]\n        if space_value in get_args(Space):\n            config[\"space\"] = space_value\n        else:\n            raise ValueError(f\"not a valid space: {space_value}\")\n    if \"ef_construction\" in json_map:\n        config[\"ef_construction\"] = json_map[\"ef_construction\"]\n    if \"max_neighbors\" in json_map:\n        config[\"max_neighbors\"] = json_map[\"max_neighbors\"]\n    if \"ef_search\" in json_map:\n        config[\"ef_search\"] = json_map[\"ef_search\"]\n    if \"num_threads\" in json_map:\n        config[\"num_threads\"] = json_map[\"num_threads\"]\n    if \"batch_size\" in json_map:\n        config[\"batch_size\"] = json_map[\"batch_size\"]\n    if \"sync_threshold\" in json_map:\n        config[\"sync_threshold\"] = json_map[\"sync_threshold\"]\n    if \"resize_factor\" in json_map:\n        config[\"resize_factor\"] = json_map[\"resize_factor\"]\n    return config\n\n\nclass CreateSpannConfiguration(TypedDict, total=False):","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/collection_configuration.py#L186-L222","documentation":"Chroma throws this ValueError from json_to_create_hnsw_configuration when a collection is created (or restored from JSON metadata) with an HNSW configuration whose 'space' key is not one of the allowed values. Valid spaces are defined by the Space literal in chromadb/api/types.py: 'cosine', 'l2', or 'ip'. The check is an exact membership test against those strings, so any spelling variant, casing change, or synonym is rejected.","triggerScenarios":"Calling client.create_collection(..., configuration={'hnsw': {'space': 'euclidean'}}) or passing configuration=CollectionConfiguration(hnsw={'space': ...}) where space is anything other than exactly 'cosine', 'l2', or 'ip'. Also triggered when older metadata like {'embedding_space': 'dot'} is translated into hnsw config, or when a config dict round-tripped from user input/JSON contains typos such as 'Cosine' or 'inner_product'.","commonSituations":"Developers migrating from other vector DBs (FAISS 'L2'/'IP', Pinecone 'cosine', pgvector '<=>') map metric names directly and hit casing or naming mismatches; users copying hnswlib docs that mention 'sqeuclidean'; configs loaded from YAML/JSON files where the value was edited by hand; upgrading Chroma versions where metadata keys were renamed to the new nested configuration format.","solutions":["Set space to one of the exact literals 'cosine', 'l2', or 'ip' (lowercase) inside configuration['hnsw']","If you want unnormalized dot-product similarity, use 'ip' and normalize vectors yourself, or use 'cosine' which normalizes internally","Validate any user- or file-supplied config against get_args(chromadb.api.types.Space) (or the literal tuple) before calling create_collection","If migrating from old flat metadata (e.g. {'hnsw:space': ...}), ensure the legacy key maps to the new nested {'hnsw': {'space': ...}} structure with a valid value"],"exampleFix":"// before\nclient.create_collection(\n    name='docs',\n    configuration={'hnsw': {'space': 'euclidean'}}  # ValueError\n)\n\n// after\nclient.create_collection(\n    name='docs',\n    configuration={'hnsw': {'space': 'l2'}}  # valid: cosine | l2 | ip\n)","handlingStrategy":"validation","validationCode":"from chromadb.api.types import Space\nfrom typing import get_args\n\nVALID_SPACES = get_args(Space)  # ('cosine', 'l2', 'ip')\n\ndef validate_hnsw_config(cfg: dict) -> None:\n    space = cfg.get('hnsw', {}).get('space')\n    if space is not None and space not in VALID_SPACES:\n        raise ValueError(f\"invalid space {space!r}; expected one of {VALID_SPACES}\")\n\nvalidate_hnsw_config(my_configuration)\nclient.create_collection(name='c', configuration=my_configuration)","typeGuard":"from typing import get_args\nfrom chromadb.api.types import Space\n\ndef is_valid_space(value: object) -> bool:\n    return isinstance(value, str) and value in get_args(Space)","tryCatchPattern":"try:\n    client.create_collection(name='c', configuration=cfg)\nexcept ValueError as e:\n    if 'not a valid space' in str(e):\n        # fix cfg['hnsw']['space'] to cosine/l2/ip and retry with a corrected name\n        ...\n    raise","preventionTips":["Validate space values against get_args(Space) before create/modify","Keep metric names lowercase and sourced from one constants module, not hand-typed strings","When loading config from YAML/JSON, run a schema check that includes an enum constraint on space"],"tags":["chroma","hnsw","configuration","vector-space","distance-metric","create-collection"],"backgroundTag":"invalid-distance-metric","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}