chroma-core/chroma · error · ValueError

An instance of Chroma already exists for {identifier} with d

Error message

An instance of Chroma already exists for {identifier} with different settings

What it means

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.

Source

Thrown at chromadb/api/shared_system_client.py:45

    @classmethod
    def _create_system_if_not_exists(
        cls, identifier: str, settings: Settings
    ) -> System:
        if identifier not in cls._identifier_to_system:
            new_system = System(settings)
            cls._identifier_to_system[identifier] = new_system

            new_system.instance(ProductTelemetryClient)
            new_system.instance(ServerAPI)

            new_system.start()
        else:
            previous_system = cls._identifier_to_system[identifier]

            # For now, the settings must match
            if previous_system.settings != settings:
                raise ValueError(
                    f"An instance of Chroma already exists for {identifier} with different settings"
                )

        return cls._identifier_to_system[identifier]

    @staticmethod
    def _get_identifier_from_settings(settings: Settings) -> str:
        identifier = ""
        api_impl = settings.chroma_api_impl

        if api_impl is None:
            raise ValueError("Chroma API implementation must be set in settings")
        elif api_impl in [
            "chromadb.api.segment.SegmentAPI",
            "chromadb.api.rust.RustBindingsAPI",
        ]:
            if settings.is_persistent:
                identifier = settings.persist_directory

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Create the client once with one canonical Settings and share it (module singleton or dependency injection)
2. Make the settings identical to the first client's — then Chroma returns the cached system instead of raising
3. Use chromadb.HttpClient for independent client configurations, or isolate conflicting settings in separate processes or persist directories

Example fix

// before
c1 = chromadb.PersistentClient(path='./db')
c2 = chromadb.PersistentClient(path='./db', settings=Settings(anonymized_telemetry=False))  # ValueError

// after
settings = Settings(anonymized_telemetry=False)
c1 = chromadb.PersistentClient(path='./db', settings=settings)
c2 = chromadb.PersistentClient(path='./db', settings=settings)  # equal settings -> shared system

_client_cache = {}

def get_chroma_client(path: str = './chroma', **settings_kwargs):
    key = (path, tuple(sorted(settings_kwargs.items())))
    if key not in _client_cache:
        import chromadb
        _client_cache[key] = chromadb.PersistentClient(path=path,
                                                       settings=Settings(**settings_kwargs))
    return _client_cache[key]

try:
    client = chromadb.PersistentClient(path=path, settings=settings)
except ValueError as e:
    if 'already exists' in str(e):
        client = chromadb.PersistentClient(path=path)  # reuse cached settings
    else:
        raise

When it happens

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

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

Related errors

• Chroma API implementation must be set in settings
• Unsupported Chroma API implementation {api_impl}
• Embedding function provided when already defined in the coll
• Aggregate input must be an Aggregate instance or object with
• MinK keys cannot be empty

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