chroma-core/chroma · error · ValueError

Chroma server host provided in settings[{settings.chroma_ser

Error message

Chroma server host provided in settings[{settings.chroma_server_host}] is different to the one provided in HttpClient: [{host}]

What it means

HttpClient() coerces its arguments (host = str(host) etc.) and then cross-checks them against Settings: if settings.chroma_server_host is already set and differs from the host argument, it raises ValueError (chromadb/__init__.py:299-303). The guard prevents a stale Settings value or environment variable from silently redirecting the client to a different server.

Source

Thrown at chromadb/__init__.py:301

        ClientAPI: A configured client instance.

    Raises:
        ValueError: If settings specify a different host or port.
    """

    if settings is None:
        settings = Settings()

    # Make sure parameters are the correct types -- users can pass anything.
    host = str(host)
    port = int(port)
    ssl = bool(ssl)
    tenant = str(tenant)
    database = str(database)

    settings.chroma_api_impl = "chromadb.api.fastapi.FastAPI"
    if settings.chroma_server_host and settings.chroma_server_host != host:
        raise ValueError(
            f"Chroma server host provided in settings[{settings.chroma_server_host}] is different to the one provided in HttpClient: [{host}]"
        )
    settings.chroma_server_host = host
    if settings.chroma_server_http_port and settings.chroma_server_http_port != port:
        raise ValueError(
            f"Chroma server http port provided in settings[{settings.chroma_server_http_port}] is different to the one provided in HttpClient: [{port}]"
        )
    settings.chroma_server_http_port = port
    settings.chroma_server_ssl_enabled = ssl
    settings.chroma_server_headers = headers

    return ClientCreator(tenant=tenant, database=database, settings=settings)


async def AsyncHttpClient(
    host: str = "localhost",
    port: int = 8000,
    ssl: bool = False,

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. Make the values agree: pass the same host, or stop setting chroma_server_host in Settings when using HttpClient's host argument
  2. Clear the stale configuration: unset the CHROMA_SERVER_HOST environment variable / remove the Settings keyword
  3. Keep a single source of truth — configure the host in exactly one place (either Settings or the HttpClient argument)

Example fix

# before
settings = Settings(chroma_server_host='localhost')
client = HttpClient('10.0.0.5', settings=settings)  # ValueError

# after
client = HttpClient('10.0.0.5')  # host set in one place only
Defensive patterns

Strategy: validation

Validate before calling

def make_client(host: str, port: int, settings: Settings) -> chromadb.api.ClientAPI:
    if settings.chroma_server_host and settings.chroma_server_host != host:
        raise ValueError(
            f'host conflict: settings={settings.chroma_server_host!r} vs argument={host!r}; '
            'unset CHROMA_SERVER_HOST or align the values'
        )
    return chromadb.HttpClient(host=host, port=port, settings=settings)

Try / catch

try:
    client = chromadb.HttpClient(host, port, settings=settings)
except ValueError as e:
    if 'server host' in str(e):
        # log the conflict, clear settings.chroma_server_host (or the env var), retry once
        raise
    raise

Prevention

When it happens

Trigger: HttpClient('10.0.0.5') while Settings(chroma_server_host='localhost') (or the corresponding env var) is still set; pointing the client at a new host without clearing the previously configured one.

Common situations: .env files copied between local and staging; CI templates that set the server host globally; code that builds Settings once and reuses it with different host arguments.

Related errors

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