chroma-core/chroma · error · ValueError

Changing the distance function of a collection once it is cr

Error message

Changing the distance function of a collection once it is created is not supported currently.

What it means

The HNSW index space (distance function: cosine, l2, ip) is baked into a collection at creation time; you cannot change it afterwards via `collection.modify(metadata=...)`. Modifying metadata with an `hnsw:space` key is explicitly rejected because the existing index would become inconsistent.

Source

Thrown at chromadb/api/models/CollectionCommon.py:554

        ):
            response["data"] = [self._data_loader(uris) for uris in response["uris"]]

        if "embeddings" in include and response["embeddings"] is not None:
            response["embeddings"] = [
                np.array(embedding) for embedding in response["embeddings"]
            ]

        # Remove URIs from the result if they weren't requested
        if "uris" not in include:
            response["uris"] = None

        return response

    def _validate_modify_request(self, metadata: Optional[CollectionMetadata]) -> None:
        if metadata is not None:
            validate_metadata(metadata)
            if "hnsw:space" in metadata:
                raise ValueError(
                    "Changing the distance function of a collection once it is created is not supported currently."
                )

    def _update_model_after_modify_success(
        self,
        name: Optional[str],
        metadata: Optional[CollectionMetadata],
        configuration: Optional[UpdateCollectionConfiguration],
    ) -> None:
        if name:
            self._model["name"] = name
        if metadata:
            self._model["metadata"] = metadata
        if configuration:
            self._model.set_configuration(
                overwrite_collection_configuration(
                    self._model.get_configuration(), configuration
                )

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Strip `hnsw:space` (and other hnsw:* creation keys) from the metadata before calling modify
2. If you truly need a different space, create a new collection with the right configuration and re-ingest (or copy) the data
3. Set the space at creation: `client.create_collection(name, configuration={"hnsw": {"space": "cosine"}})` (or metadata={"hnsw:space": ...} on older versions)

Example fix

# before
md = dict(collection.metadata)
md["owner"] = "team-a"  # md still contains hnsw:space
collection.modify(metadata=md)  # ValueError

# after
md = {k: v for k, v in collection.metadata.items() if not k.startswith("hnsw:")}
md["owner"] = "team-a"
collection.modify(metadata=md)

new_metadata = {k: v for k, v in (metadata or {}).items() if k != "hnsw:space"}
collection.modify(metadata=new_metadata)

When it happens

Trigger: `collection.modify(metadata={"hnsw:space": "cosine"})` (or metadata that still contains the hnsw:space key from `collection.metadata`).

Common situations: Copying the collection's own metadata (which includes hnsw:space), updating another key, and passing the whole dict back to modify; deciding late that a different distance metric was needed.

Related errors

• Invalid legacy HNSW parameter name: {name}
• 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/961caf804d5465ab. Report an issue: GitHub.