{"record":{"id":"1f5d1617b558f4ee","repo":"chroma-core/chroma","slug":"an-instance-of-chroma-already-exists-for-identifi","errorCode":null,"errorMessage":"An instance of Chroma already exists for {identifier} with different settings","messagePattern":"An instance of Chroma already exists for (.+?) with different settings","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/shared_system_client.py","lineNumber":45,"sourceCode":"\n    @classmethod\n    def _create_system_if_not_exists(\n        cls, identifier: str, settings: Settings\n    ) -> System:\n        if identifier not in cls._identifier_to_system:\n            new_system = System(settings)\n            cls._identifier_to_system[identifier] = new_system\n\n            new_system.instance(ProductTelemetryClient)\n            new_system.instance(ServerAPI)\n\n            new_system.start()\n        else:\n            previous_system = cls._identifier_to_system[identifier]\n\n            # For now, the settings must match\n            if previous_system.settings != settings:\n                raise ValueError(\n                    f\"An instance of Chroma already exists for {identifier} with different settings\"\n                )\n\n        return cls._identifier_to_system[identifier]\n\n    @staticmethod\n    def _get_identifier_from_settings(settings: Settings) -> str:\n        identifier = \"\"\n        api_impl = settings.chroma_api_impl\n\n        if api_impl is None:\n            raise ValueError(\"Chroma API implementation must be set in settings\")\n        elif api_impl in [\n            \"chromadb.api.segment.SegmentAPI\",\n            \"chromadb.api.rust.RustBindingsAPI\",\n        ]:\n            if settings.is_persistent:\n                identifier = settings.persist_directory","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/shared_system_client.py#L27-L63","documentation":"SharedSystemClient caches one System per identifier — for embedded clients the identifier is the persist directory (or 'ephemeral'). When a second client is created with the same identifier, it compares the new Settings against the cached system's; if they differ at all (telemetry flag, hnsw knobs, etc.), it raises ValueError('An instance of Chroma already exists for {identifier} with different settings'). The check is whole-object equality, so any single differing field triggers it.","triggerScenarios":"In one process: chromadb.PersistentClient(path='./db', settings=Settings(anonymized_telemetry=False)) after a PersistentClient on the same path was already created with default (different) settings; similarly two EphemeralClients with differing settings.","commonSituations":"A library or framework plugin constructs its own internal client while the host app also creates one on the same path; toggling telemetry (or other settings) between test cases without a fresh process/path; utilities that build Settings from per-request config.","solutions":["Create the client once with one canonical Settings and share it (module singleton or dependency injection)","Make the settings identical to the first client's — then Chroma returns the cached system instead of raising","Use chromadb.HttpClient for independent client configurations, or isolate conflicting settings in separate processes or persist directories"],"exampleFix":"// before\nc1 = chromadb.PersistentClient(path='./db')\nc2 = chromadb.PersistentClient(path='./db', settings=Settings(anonymized_telemetry=False))  # ValueError\n\n// after\nsettings = Settings(anonymized_telemetry=False)\nc1 = chromadb.PersistentClient(path='./db', settings=settings)\nc2 = chromadb.PersistentClient(path='./db', settings=settings)  # equal settings -> shared system","handlingStrategy":"validation","validationCode":"_client_cache = {}\n\ndef get_chroma_client(path: str = './chroma', **settings_kwargs):\n    key = (path, tuple(sorted(settings_kwargs.items())))\n    if key not in _client_cache:\n        import chromadb\n        _client_cache[key] = chromadb.PersistentClient(path=path,\n                                                       settings=Settings(**settings_kwargs))\n    return _client_cache[key]","typeGuard":null,"tryCatchPattern":"try:\n    client = chromadb.PersistentClient(path=path, settings=settings)\nexcept ValueError as e:\n    if 'already exists' in str(e):\n        client = chromadb.PersistentClient(path=path)  # reuse cached settings\n    else:\n        raise","preventionTips":["Create exactly one client per process per persist directory and share it via DI","Build Settings in one place from one config source so every caller passes identical values","Treat telemetry/hnsw knobs as process-wide constants, not per-call options"],"tags":["chroma","client","settings","singleton","persistent-client"],"backgroundTag":"singleton-client-settings-conflict","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}