chroma-core/chroma · error · ValueError

Chroma API implementation must be set in settings

Error message

Chroma API implementation must be set in settings

What it means

Before a client is built, SharedSystemClient._get_identifier_from_settings reads settings.chroma_api_impl to compute the cache identifier; if it is None it raises ValueError('Chroma API implementation must be set in settings'). The factory helpers (EphemeralClient/PersistentClient/HttpClient) populate this field, so hitting the error usually means a Settings object was hand-built or deserialized without an api impl and passed straight to Client/SharedSystemClient.

Source

Thrown at chromadb/api/shared_system_client.py:57

            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
            else:
                identifier = (
                    "ephemeral"  # TODO: support pathing and  multiple ephemeral clients
                )
        elif api_impl in [
            "chromadb.api.fastapi.FastAPI",
            "chromadb.api.async_fastapi.AsyncFastAPI",
        ]:
            # FastAPI clients can all use unique system identifiers since their configurations can be independent, e.g. different auth tokens
            identifier = str(uuid.uuid4())
        else:
            raise ValueError(f"Unsupported Chroma API implementation {api_impl}")

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Use the factory helpers (chromadb.PersistentClient / EphemeralClient / HttpClient), which set the impl for you
2. Set the impl explicitly: Settings(chroma_api_impl='chromadb.api.segment.SegmentAPI') for embedded
3. Check settings.chroma_api_impl for None before constructing the client and fail fast with a clear message

Example fix

// before
client = chromadb.Client(settings=Settings(is_persistent=True))  # chroma_api_impl is None -> ValueError

// after
client = chromadb.PersistentClient(path='./chroma')  # factory sets the impl

from chromadb.config import Settings

def make_client(settings: Settings):
    if settings.chroma_api_impl is None:
        raise ValueError('chroma_api_impl must be set; use PersistentClient/EphemeralClient/HttpClient')
    return chromadb.Client(settings=settings)

def has_api_impl(settings) -> bool:
    return settings.chroma_api_impl is not None

When it happens

Trigger: chromadb.Client(settings=Settings(...)) (or direct SharedSystemClient use) where chroma_api_impl was never set — e.g. Settings(is_persistent=True) constructed manually, or settings loaded from env/file with CHROMA_API_IMPL unset.

Common situations: Building Settings programmatically instead of using the factory clients; partially copied configuration code; environments where the CHROMA_API_IMPL variable is absent and settings are assembled from scratch.

Related errors

• Unsupported Chroma API implementation {api_impl}
• Auth provider not specified
• Auth credentials not specified
• Invalid auth provider
• Embedding function provided when already defined in the coll

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