chroma-core/chroma · error · ValueError

Unsupported Chroma API implementation {api_impl}

Error message

Unsupported Chroma API implementation {api_impl}

What it means

_get_identifier_from_settings recognizes only a fixed set of api-impl class strings: 'chromadb.api.segment.SegmentAPI' and 'chromadb.api.rust.RustBindingsAPI' (embedded, identified by persist path) and the FastAPI server impls. Any other string falls to the else branch and raises ValueError('Unsupported Chroma API implementation {api_impl}').

Source

Thrown at chromadb/api/shared_system_client.py:75

            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}")

        return identifier

    @staticmethod
    def _populate_data_from_system(system: System) -> str:
        identifier = SharedSystemClient._get_identifier_from_settings(system.settings)
        SharedSystemClient._identifier_to_system[identifier] = system
        return identifier

    @classmethod
    def from_system(cls, system: System) -> "SharedSystemClient":
        """Create a client from an existing system. This is useful for testing and debugging."""

        SharedSystemClient._populate_data_from_system(system)
        instance = cls(system.settings)
        return instance

    @classmethod

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Use an exact supported value, e.g. 'chromadb.api.segment.SegmentAPI' for embedded
2. Prefer the factory clients (PersistentClient/EphemeralClient/HttpClient) so the impl string is never hand-typed
3. After upgrading chromadb, regenerate settings/env instead of forwarding old impl names

Example fix

// before
settings = Settings(chroma_api_impl='chromadb.api.local.LocalAPI')  # removed impl -> ValueError

// after
client = chromadb.PersistentClient(path='./chroma')  # factory chooses a supported impl

SUPPORTED_IMPLS = {
    'chromadb.api.segment.SegmentAPI',
    'chromadb.api.rust.RustBindingsAPI',
}

def make_client(settings):
    impl = settings.chroma_api_impl
    if impl not in SUPPORTED_IMPLS:
        raise ValueError(f'unsupported chroma_api_impl {impl!r}; expected one of {sorted(SUPPORTED_IMPLS)}')
    return chromadb.Client(settings=settings)

def is_supported_api_impl(value: str) -> bool:
    return value in ('chromadb.api.segment.SegmentAPI',
                     'chromadb.api.rust.RustBindingsAPI')

When it happens

Trigger: Passing Settings(chroma_api_impl=<string>) where the string is not one of the supported class paths — misspellings like 'chromadb.api.segment' or 'SegmentAPI', or legacy values such as 'chromadb.api.local.LocalAPI' removed in newer versions.

Common situations: Upgrading chromadb while carrying old settings files/env values with removed impl names; typos in CHROMA_API_IMPL; custom or experimental impl class strings never added to this list.

Related errors

• Chroma API implementation must be set in settings
• Embedding function provided when already defined in the coll
• Chroma server host provided in settings[{settings.chroma_ser
• Chroma server http port provided in settings[{settings.chrom
• Invalid URL. Unrecognized protocol - {parsed.scheme}.

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