{"record":{"id":"569b16135f3fe397","repo":"chroma-core/chroma","slug":"chroma-api-implementation-must-be-set-in-settings","errorCode":null,"errorMessage":"Chroma API implementation must be set in settings","messagePattern":"Chroma API implementation must be set in settings","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/shared_system_client.py","lineNumber":57,"sourceCode":"            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\n            else:\n                identifier = (\n                    \"ephemeral\"  # TODO: support pathing and  multiple ephemeral clients\n                )\n        elif api_impl in [\n            \"chromadb.api.fastapi.FastAPI\",\n            \"chromadb.api.async_fastapi.AsyncFastAPI\",\n        ]:\n            # FastAPI clients can all use unique system identifiers since their configurations can be independent, e.g. different auth tokens\n            identifier = str(uuid.uuid4())\n        else:\n            raise ValueError(f\"Unsupported Chroma API implementation {api_impl}\")","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/shared_system_client.py#L39-L75","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use the factory helpers (chromadb.PersistentClient / EphemeralClient / HttpClient), which set the impl for you","Set the impl explicitly: Settings(chroma_api_impl='chromadb.api.segment.SegmentAPI') for embedded","Check settings.chroma_api_impl for None before constructing the client and fail fast with a clear message"],"exampleFix":"// before\nclient = chromadb.Client(settings=Settings(is_persistent=True))  # chroma_api_impl is None -> ValueError\n\n// after\nclient = chromadb.PersistentClient(path='./chroma')  # factory sets the impl","handlingStrategy":"validation","validationCode":"from chromadb.config import Settings\n\ndef make_client(settings: Settings):\n    if settings.chroma_api_impl is None:\n        raise ValueError('chroma_api_impl must be set; use PersistentClient/EphemeralClient/HttpClient')\n    return chromadb.Client(settings=settings)","typeGuard":"def has_api_impl(settings) -> bool:\n    return settings.chroma_api_impl is not None","tryCatchPattern":null,"preventionTips":["Prefer factory clients (PersistentClient/EphemeralClient/HttpClient) over hand-built Settings","If you must build Settings programmatically, set chroma_api_impl explicitly and assert it before client creation"],"tags":["chroma","settings","configuration","api-impl","client-construction"],"backgroundTag":"missing-configuration-value","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}