{"record":{"id":"67529b02fe4c479f","repo":"chroma-core/chroma","slug":"chroma-is-running-in-http-only-client-mode-and-ca","errorCode":null,"errorMessage":"Chroma is running in http-only client mode, and can only be run with 'chromadb.api.fastapi.FastAPI' or 'chromadb.api.async_fastapi.AsyncFastAPI' as the chroma_api_impl.             see https://docs.trychroma.com/guides#using-the-python-http-only-client for more information.","messagePattern":"Chroma is running in http-only client mode, and can only be run with 'chromadb\\.api\\.fastapi\\.FastAPI' or 'chromadb\\.api\\.async_fastapi\\.AsyncFastAPI' as the chroma_api_impl\\.             see https://docs\\.trychroma\\.com/guides#using-the-python-http-only-client for more information\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"chromadb/config.py","lineNumber":375,"sourceCode":"\n    def reset_state(self) -> None:\n        \"\"\"Reset this component's state to its initial blank state. Only intended to be\n        called from tests.\"\"\"\n        logger.debug(f\"Resetting component {self.__class__.__name__}\")\n\n\nclass System(Component):\n    settings: Settings\n    _instances: Dict[Type[Component], Component]\n\n    def __init__(self, settings: Settings):\n        if is_thin_client:\n            # The thin client is a system with only the API component\n            if settings[\"chroma_api_impl\"] not in [\n                \"chromadb.api.fastapi.FastAPI\",\n                \"chromadb.api.async_fastapi.AsyncFastAPI\",\n            ]:\n                raise RuntimeError(\n                    \"Chroma is running in http-only client mode, and can only be run with 'chromadb.api.fastapi.FastAPI' or 'chromadb.api.async_fastapi.AsyncFastAPI' as the chroma_api_impl. \\\n            see https://docs.trychroma.com/guides#using-the-python-http-only-client for more information.\"\n                )\n        # Validate settings don't contain any legacy config values\n        for key in _legacy_config_keys:\n            if settings[key] is not None:\n                raise ValueError(LEGACY_ERROR)\n\n        if (\n            settings[\"chroma_segment_cache_policy\"] is not None\n            and settings[\"chroma_segment_cache_policy\"] != \"LRU\"\n        ):\n            logger.error(\n                \"Failed to set chroma_segment_cache_policy: Only LRU is available.\"\n            )\n            if settings[\"chroma_memory_limit_bytes\"] == 0:\n                logger.error(\n                    \"Failed to set chroma_segment_cache_policy: chroma_memory_limit_bytes is require.\"","sourceCodeStart":357,"sourceCodeEnd":393,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/config.py#L357-L393","documentation":"RuntimeError raised in System.__init__ (chromadb/config.py) when the installed distribution is the thin HTTP-only client (`chromadb-client` wheel, detected via chromadb.is_thin_client) but chroma_api_impl is set to anything other than 'chromadb.api.fastapi.FastAPI' or 'chromadb.api.async_fastapi.AsyncFastAPI'. The thin wheel ships no server or segment code, so embedded/local implementations cannot run in that process.","triggerScenarios":"pip install chromadb-client followed by code that assumes embedded mode (EphemeralClient/PersistentClient) or that overrides chroma_api_impl to a local impl; environments where the thin wheel shadows a full chromadb install.","commonSituations":"Docker images that install chromadb-client to save space but run local-mode code; both chromadb and chromadb-client installed side by side, with the thin one winning; tutorials written for the full package executed against the thin one.","solutions":["With the thin client, use the HTTP constructors (chromadb.HttpClient() / AsyncHttpClient()) and do not set chroma_api_impl.","If you need embedded/persistent local mode, install the full `chromadb` package instead of `chromadb-client`.","Uninstall one of the two distributions to avoid the thin wheel shadowing the full one: pip uninstall chromadb-client (or vice versa), then reinstall the one you keep."],"exampleFix":"// before (with chromadb-client installed)\nclient = chromadb.PersistentClient(path='./data')  # RuntimeError: http-only client mode\n\n// after (pick one)\nclient = chromadb.HttpClient(host='localhost', port=8000)  # stay thin\n# or: pip uninstall chromadb-client && pip install chromadb\nclient = chromadb.PersistentClient(path='./data')","handlingStrategy":"validation","validationCode":"from chromadb.is_thin_client import is_thin_client\nimport chromadb\n\nif is_thin_client:\n    # http-only wheel: never set chroma_api_impl\n    client = chromadb.HttpClient(host='localhost', port=8000)\nelse:\n    client = chromadb.PersistentClient(path='./data')","typeGuard":"def is_thin_client_install() -> bool:\n    try:\n        from chromadb.is_thin_client import is_thin_client  # only importable in the thin wheel\n        return is_thin_client\n    except ImportError:\n        return False","tryCatchPattern":"try:\n    system = System(settings)\nexcept RuntimeError as e:\n    if 'http-only client mode' in str(e):\n        raise RuntimeError('install full chromadb for embedded mode, or use HttpClient()') from e\n    raise","preventionTips":["Install exactly one of chromadb / chromadb-client per environment; pin it in requirements.","Let the client constructors pick chroma_api_impl - do not set it manually.","Document for your team which wheel each deployment uses."],"tags":["client-mode","thin-client","configuration","runtimeerror"],"backgroundTag":"thin-client-restriction","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}