chroma-core/chroma · error · ValueError

not a valid space: {space_value}

Error message

not a valid space: {space_value}

What it means

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.

Source

Thrown at chromadb/api/collection_configuration.py:204

    ef_construction: int
    max_neighbors: int
    ef_search: int
    num_threads: int
    batch_size: int
    sync_threshold: int
    resize_factor: float


def json_to_create_hnsw_configuration(
    json_map: Dict[str, Any]
) -> CreateHNSWConfiguration:
    config: CreateHNSWConfiguration = {}
    if "space" in json_map:
        space_value = json_map["space"]
        if space_value in get_args(Space):
            config["space"] = space_value
        else:
            raise ValueError(f"not a valid space: {space_value}")
    if "ef_construction" in json_map:
        config["ef_construction"] = json_map["ef_construction"]
    if "max_neighbors" in json_map:
        config["max_neighbors"] = json_map["max_neighbors"]
    if "ef_search" in json_map:
        config["ef_search"] = json_map["ef_search"]
    if "num_threads" in json_map:
        config["num_threads"] = json_map["num_threads"]
    if "batch_size" in json_map:
        config["batch_size"] = json_map["batch_size"]
    if "sync_threshold" in json_map:
        config["sync_threshold"] = json_map["sync_threshold"]
    if "resize_factor" in json_map:
        config["resize_factor"] = json_map["resize_factor"]
    return config


class CreateSpannConfiguration(TypedDict, total=False):

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Set space to one of the exact literals 'cosine', 'l2', or 'ip' (lowercase) inside configuration['hnsw']
2. If you want unnormalized dot-product similarity, use 'ip' and normalize vectors yourself, or use 'cosine' which normalizes internally
3. Validate any user- or file-supplied config against get_args(chromadb.api.types.Space) (or the literal tuple) before calling create_collection
4. 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

Example fix

// before
client.create_collection(
    name='docs',
    configuration={'hnsw': {'space': 'euclidean'}}  # ValueError
)

// after
client.create_collection(
    name='docs',
    configuration={'hnsw': {'space': 'l2'}}  # valid: cosine | l2 | ip
)

from chromadb.api.types import Space
from typing import get_args

VALID_SPACES = get_args(Space)  # ('cosine', 'l2', 'ip')

def validate_hnsw_config(cfg: dict) -> None:
    space = cfg.get('hnsw', {}).get('space')
    if space is not None and space not in VALID_SPACES:
        raise ValueError(f"invalid space {space!r}; expected one of {VALID_SPACES}")

validate_hnsw_config(my_configuration)
client.create_collection(name='c', configuration=my_configuration)

from typing import get_args
from chromadb.api.types import Space

def is_valid_space(value: object) -> bool:
    return isinstance(value, str) and value in get_args(Space)

try:
    client.create_collection(name='c', configuration=cfg)
except ValueError as e:
    if 'not a valid space' in str(e):
        # fix cfg['hnsw']['space'] to cosine/l2/ip and retry with a corrected name
        ...
    raise

When it happens

Trigger: 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'.

Common situations: 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.

Related errors

• Multiple embedding functions provided. Please provide only o
• Cannot specify both 'hnsw' and 'spann' configurations during
• Invalid HNSW config provided in CreateCollectionConfiguratio
• Cannot specify both 'hnsw' and 'spann' configurations during
• Invalid HNSW config provided in UpdateCollectionConfiguratio

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