{"record":{"id":"961caf804d5465ab","repo":"chroma-core/chroma","slug":"changing-the-distance-function-of-a-collection-onc","errorCode":null,"errorMessage":"Changing the distance function of a collection once it is created is not supported currently.","messagePattern":"Changing the distance function of a collection once it is created is not supported currently\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/models/CollectionCommon.py","lineNumber":554,"sourceCode":"        ):\n            response[\"data\"] = [self._data_loader(uris) for uris in response[\"uris\"]]\n\n        if \"embeddings\" in include and response[\"embeddings\"] is not None:\n            response[\"embeddings\"] = [\n                np.array(embedding) for embedding in response[\"embeddings\"]\n            ]\n\n        # Remove URIs from the result if they weren't requested\n        if \"uris\" not in include:\n            response[\"uris\"] = None\n\n        return response\n\n    def _validate_modify_request(self, metadata: Optional[CollectionMetadata]) -> None:\n        if metadata is not None:\n            validate_metadata(metadata)\n            if \"hnsw:space\" in metadata:\n                raise ValueError(\n                    \"Changing the distance function of a collection once it is created is not supported currently.\"\n                )\n\n    def _update_model_after_modify_success(\n        self,\n        name: Optional[str],\n        metadata: Optional[CollectionMetadata],\n        configuration: Optional[UpdateCollectionConfiguration],\n    ) -> None:\n        if name:\n            self._model[\"name\"] = name\n        if metadata:\n            self._model[\"metadata\"] = metadata\n        if configuration:\n            self._model.set_configuration(\n                overwrite_collection_configuration(\n                    self._model.get_configuration(), configuration\n                )","sourceCodeStart":536,"sourceCodeEnd":572,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/models/CollectionCommon.py#L536-L572","documentation":"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.","triggerScenarios":"`collection.modify(metadata={\"hnsw:space\": \"cosine\"})` (or metadata that still contains the hnsw:space key from `collection.metadata`).","commonSituations":"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.","solutions":["Strip `hnsw:space` (and other hnsw:* creation keys) from the metadata before calling modify","If you truly need a different space, create a new collection with the right configuration and re-ingest (or copy) the data","Set the space at creation: `client.create_collection(name, configuration={\"hnsw\": {\"space\": \"cosine\"}})` (or metadata={\"hnsw:space\": ...} on older versions)"],"exampleFix":"# before\nmd = dict(collection.metadata)\nmd[\"owner\"] = \"team-a\"  # md still contains hnsw:space\ncollection.modify(metadata=md)  # ValueError\n\n# after\nmd = {k: v for k, v in collection.metadata.items() if not k.startswith(\"hnsw:\")}\nmd[\"owner\"] = \"team-a\"\ncollection.modify(metadata=md)","handlingStrategy":"validation","validationCode":"new_metadata = {k: v for k, v in (metadata or {}).items() if k != \"hnsw:space\"}\ncollection.modify(metadata=new_metadata)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never echo a collection's own metadata back into modify() unfiltered","Choose distance function at creation time; plan a re-ingest if it must change","Strip all hnsw:* keys from modify payloads, not just hnsw:space"],"tags":["metadata","hnsw","distance-function","modify","immutable-config"],"backgroundTag":"immutable-collection-config","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}