{"record":{"id":"562c5834a4f3846e","repo":"chroma-core/chroma","slug":"chroma-server-http-port-provided-in-settings-sett","errorCode":null,"errorMessage":"Chroma server http port provided in settings[{settings.chroma_server_http_port}] is different to the one provided in HttpClient: [{port}]","messagePattern":"Chroma server http port provided in settings\\[(.+?)\\] is different to the one provided in HttpClient: \\[(.+?)\\]","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/__init__.py","lineNumber":306,"sourceCode":"\n    if settings is None:\n        settings = Settings()\n\n    # Make sure parameters are the correct types -- users can pass anything.\n    host = str(host)\n    port = int(port)\n    ssl = bool(ssl)\n    tenant = str(tenant)\n    database = str(database)\n\n    settings.chroma_api_impl = \"chromadb.api.fastapi.FastAPI\"\n    if settings.chroma_server_host and settings.chroma_server_host != host:\n        raise ValueError(\n            f\"Chroma server host provided in settings[{settings.chroma_server_host}] is different to the one provided in HttpClient: [{host}]\"\n        )\n    settings.chroma_server_host = host\n    if settings.chroma_server_http_port and settings.chroma_server_http_port != port:\n        raise ValueError(\n            f\"Chroma server http port provided in settings[{settings.chroma_server_http_port}] is different to the one provided in HttpClient: [{port}]\"\n        )\n    settings.chroma_server_http_port = port\n    settings.chroma_server_ssl_enabled = ssl\n    settings.chroma_server_headers = headers\n\n    return ClientCreator(tenant=tenant, database=database, settings=settings)\n\n\nasync def AsyncHttpClient(\n    host: str = \"localhost\",\n    port: int = 8000,\n    ssl: bool = False,\n    headers: Optional[Dict[str, str]] = None,\n    settings: Optional[Settings] = None,\n    tenant: str = DEFAULT_TENANT,\n    database: str = DEFAULT_DATABASE,\n) -> AsyncClientAPI:","sourceCodeStart":288,"sourceCodeEnd":324,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/__init__.py#L288-L324","documentation":"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.","triggerScenarios":"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.","commonSituations":"Leftover port settings in .env or CI variables; running a non-default `chroma run --port` and passing the new port while old config persists.","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"],"exampleFix":"# before\nsettings = Settings(chroma_server_http_port=8000)\nclient = HttpClient('localhost', 8001, settings=settings)  # ValueError\n\n# after\nclient = HttpClient('localhost', 8001)  # port configured in one place","handlingStrategy":"validation","validationCode":"def make_client(host: str, port: int, settings: Settings) -> chromadb.api.ClientAPI:\n    if settings.chroma_server_http_port and settings.chroma_server_http_port != port:\n        raise ValueError(\n            f'port conflict: settings={settings.chroma_server_http_port} vs argument={port}; '\n            'unset CHROMA_SERVER_HTTP_PORT or align the values'\n        )\n    return chromadb.HttpClient(host=host, port=port, settings=settings)","typeGuard":null,"tryCatchPattern":"try:\n    client = chromadb.HttpClient(host, port, settings=settings)\nexcept ValueError as e:\n    if 'http port' in str(e):\n        # clear settings.chroma_server_http_port / CHROMA_SERVER_HTTP_PORT and retry\n        raise\n    raise","preventionTips":["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"],"tags":["python","configuration","connection","settings","env-vars"],"backgroundTag":"connection-config-mismatch","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}