chroma-core/chroma · error · ValueError

Chroma server http port provided in settings[{settings.chrom

Error message

Chroma server http port provided in settings[{settings.chroma_server_http_port}] is different to the one provided in HttpClient: [{port}]

What it means

After the host check, HttpClient() applies the same cross-check to ports: if settings.chroma_server_http_port is already set (via Settings or environment) and differs from the int-coerced port argument, it raises ValueError (chromadb/__init__.py:304-308). This prevents silently talking to the right host on the wrong port.

Source

Thrown at chromadb/__init__.py:306

    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,
    headers: Optional[Dict[str, str]] = None,
    settings: Optional[Settings] = None,
    tenant: str = DEFAULT_TENANT,
    database: str = DEFAULT_DATABASE,
) -> AsyncClientAPI:

View on GitHub (pinned to aecdd12c8a)

Solutions

Align the values: pass the same port, or remove chroma_server_http_port from Settings
Unset the stale CHROMA_SERVER_HTTP_PORT environment variable
Centralize port configuration in one place instead of both Settings and the constructor argument

Example fix

# before
settings = Settings(chroma_server_http_port=8000)
client = HttpClient('localhost', 8001, settings=settings)  # ValueError

# after
client = HttpClient('localhost', 8001)  # port configured in one place

Defensive patterns

Strategy: validation

Validate before calling

def make_client(host: str, port: int, settings: Settings) -> chromadb.api.ClientAPI:
    if settings.chroma_server_http_port and settings.chroma_server_http_port != port:
        raise ValueError(
            f'port conflict: settings={settings.chroma_server_http_port} vs argument={port}; '
            'unset CHROMA_SERVER_HTTP_PORT 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 'http port' in str(e):
        # clear settings.chroma_server_http_port / CHROMA_SERVER_HTTP_PORT and retry
        raise
    raise

Prevention

Set the port in one location only (Settings or the constructor argument)
After moving `chroma run` to a new port, update or unset stale env vars
Add a startup assertion that compares Settings against the intended endpoint

When it happens

Trigger: HttpClient('localhost', 8001) while CHROMA_SERVER_HTTP_PORT / Settings(chroma_server_http_port=8000) is set; changing the port argument after a server move without updating the environment.

Common situations: Leftover port settings in .env or CI variables; running a non-default `chroma run --port` and passing the new port while old config persists.

Related errors

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