{"record":{"id":"2c914165ade77e9c","repo":"chroma-core/chroma","slug":"unsupported-chroma-api-implementation-api-impl","errorCode":null,"errorMessage":"Unsupported Chroma API implementation {api_impl}","messagePattern":"Unsupported Chroma API implementation (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/shared_system_client.py","lineNumber":75,"sourceCode":"            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}\")\n\n        return identifier\n\n    @staticmethod\n    def _populate_data_from_system(system: System) -> str:\n        identifier = SharedSystemClient._get_identifier_from_settings(system.settings)\n        SharedSystemClient._identifier_to_system[identifier] = system\n        return identifier\n\n    @classmethod\n    def from_system(cls, system: System) -> \"SharedSystemClient\":\n        \"\"\"Create a client from an existing system. This is useful for testing and debugging.\"\"\"\n\n        SharedSystemClient._populate_data_from_system(system)\n        instance = cls(system.settings)\n        return instance\n\n    @classmethod","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/shared_system_client.py#L57-L93","documentation":"_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}').","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use an exact supported value, e.g. 'chromadb.api.segment.SegmentAPI' for embedded","Prefer the factory clients (PersistentClient/EphemeralClient/HttpClient) so the impl string is never hand-typed","After upgrading chromadb, regenerate settings/env instead of forwarding old impl names"],"exampleFix":"// before\nsettings = Settings(chroma_api_impl='chromadb.api.local.LocalAPI')  # removed impl -> ValueError\n\n// after\nclient = chromadb.PersistentClient(path='./chroma')  # factory chooses a supported impl","handlingStrategy":"validation","validationCode":"SUPPORTED_IMPLS = {\n    'chromadb.api.segment.SegmentAPI',\n    'chromadb.api.rust.RustBindingsAPI',\n}\n\ndef make_client(settings):\n    impl = settings.chroma_api_impl\n    if impl not in SUPPORTED_IMPLS:\n        raise ValueError(f'unsupported chroma_api_impl {impl!r}; expected one of {sorted(SUPPORTED_IMPLS)}')\n    return chromadb.Client(settings=settings)","typeGuard":"def is_supported_api_impl(value: str) -> bool:\n    return value in ('chromadb.api.segment.SegmentAPI',\n                     'chromadb.api.rust.RustBindingsAPI')","tryCatchPattern":null,"preventionTips":["Never hand-type impl strings — use the factory clients","After upgrading chromadb, sweep settings files and env for stale impl names","Add a startup config validation step that whitelists impl values"],"tags":["chroma","settings","configuration","api-impl","version-migration"],"backgroundTag":"unsupported-configuration-value","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}