chroma-core/chroma · error · RuntimeError

Chroma is running in http-only client mode, and can only be

Error message

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.

What it means

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.

Source

Thrown at chromadb/config.py:375

    def reset_state(self) -> None:
        """Reset this component's state to its initial blank state. Only intended to be
        called from tests."""
        logger.debug(f"Resetting component {self.__class__.__name__}")


class System(Component):
    settings: Settings
    _instances: Dict[Type[Component], Component]

    def __init__(self, settings: Settings):
        if is_thin_client:
            # The thin client is a system with only the API component
            if settings["chroma_api_impl"] not in [
                "chromadb.api.fastapi.FastAPI",
                "chromadb.api.async_fastapi.AsyncFastAPI",
            ]:
                raise RuntimeError(
                    "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."
                )
        # Validate settings don't contain any legacy config values
        for key in _legacy_config_keys:
            if settings[key] is not None:
                raise ValueError(LEGACY_ERROR)

        if (
            settings["chroma_segment_cache_policy"] is not None
            and settings["chroma_segment_cache_policy"] != "LRU"
        ):
            logger.error(
                "Failed to set chroma_segment_cache_policy: Only LRU is available."
            )
            if settings["chroma_memory_limit_bytes"] == 0:
                logger.error(
                    "Failed to set chroma_segment_cache_policy: chroma_memory_limit_bytes is require."

View on GitHub (pinned to aecdd12c8a)

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.

Example fix

// before (with chromadb-client installed)
client = chromadb.PersistentClient(path='./data')  # RuntimeError: http-only client mode

// after (pick one)
client = chromadb.HttpClient(host='localhost', port=8000)  # stay thin
# or: pip uninstall chromadb-client && pip install chromadb
client = chromadb.PersistentClient(path='./data')

Defensive patterns

Strategy: validation

Validate before calling

from chromadb.is_thin_client import is_thin_client
import chromadb

if is_thin_client:
    # http-only wheel: never set chroma_api_impl
    client = chromadb.HttpClient(host='localhost', port=8000)
else:
    client = chromadb.PersistentClient(path='./data')

Type guard

def is_thin_client_install() -> bool:
    try:
        from chromadb.is_thin_client import is_thin_client  # only importable in the thin wheel
        return is_thin_client
    except ImportError:
        return False

Try / catch

try:
    system = System(settings)
except RuntimeError as e:
    if 'http-only client mode' in str(e):
        raise RuntimeError('install full chromadb for embedded mode, or use HttpClient()') from e
    raise

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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