{"record":{"id":"d6887eea40d099df","repo":"chroma-core/chroma","slug":"resp-text-trace-id-trace-id","errorCode":null,"errorMessage":"{resp.text} (trace ID: {trace_id})","messagePattern":"(.+?) \\(trace ID: (.+?)\\)","errorType":"http","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"chromadb/api/base_http_client.py","lineNumber":154,"sourceCode":"                \"Chroma error response missing required 'message' field: \"\n                f\"{resp.text}\"\n            )\n            trace_id = resp.headers.get(\"chroma-trace-id\")\n            if trace_id:\n                message = f\"{message} (trace ID: {trace_id})\"\n            raise ValueError(message) from e\n        except BaseException:\n            pass\n\n        if chroma_error:\n            raise chroma_error\n\n        try:\n            resp.raise_for_status()\n        except httpx.HTTPStatusError:\n            trace_id = resp.headers.get(\"chroma-trace-id\")\n            if trace_id:\n                raise Exception(f\"{resp.text} (trace ID: {trace_id})\")\n            raise (Exception(resp.text))\n\n    def get_request_headers(self) -> Mapping[str, str]:\n        \"\"\"Return headers used for HTTP requests.\"\"\"\n        return {}\n\n    def get_api_url(self) -> str:\n        \"\"\"Return the API URL for this client.\"\"\"\n        return \"\"\n","sourceCodeStart":136,"sourceCodeEnd":164,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/base_http_client.py#L136-L164","documentation":"Final fallback in _raise_chroma_error: the response had an error status, but its body did not map to any registered ChromaError type, so the client raises a bare Exception carrying the raw response text (plus the chroma-trace-id header when present). Because this is a plain Exception and not a ChromaError, `except ChromaError` handlers will not catch it.","triggerScenarios":"A reverse proxy returning 502/504 HTML pages when Chroma is down or slow; an API gateway's rate-limit response; FastAPI 422 validation responses ({\"detail\": [...]}) from hitting a route with bad parameters; connecting to a non-Chroma service on the same port.","commonSituations":"Chroma behind nginx/traefik/ALB where infrastructure errors surface as raw HTML/text; gateway timeouts on large queries; wrong service targeted in a shared cluster.","solutions":["Read the exception message — it contains the raw response body, which identifies the origin (nginx error page, gateway JSON, etc.).","If it is proxy-generated, fix the proxy config or the backend availability it complains about.","Confirm the URL actually points at Chroma: curl http://<host>:<port>/api/v2/heartbeat.","In code behind a proxy, catch plain Exception after ChromaError in your handler chain."],"exampleFix":"# before\ntry:\n    col = client.get_collection(\"docs\")\nexcept ChromaError:\n    ...  # misses bare Exception from proxy responses\n\n# after\ntry:\n    col = client.get_collection(\"docs\")\nexcept ChromaError:\n    ...\nexcept Exception as e:  # non-Chroma HTTP failure (proxy 502, 422, ...)\n    logger.error(\"raw server/proxy response: %s\", e)","handlingStrategy":"try-catch","validationCode":"import httpx\n\ndef points_at_chroma(host: str, port: int) -> bool:\n    try:\n        return httpx.get(f\"http://{host}:{port}/api/v2/heartbeat\", timeout=2).status_code == 200\n    except httpx.HTTPError:\n        return False","typeGuard":null,"tryCatchPattern":"from chromadb.errors import ChromaError\n\ntry:\n    result = collection.query(query_texts=[\"x\"])\nexcept ChromaError:\n    raise  # structured Chroma error\nexcept Exception as e:  # bare Exception(resp.text) from non-Chroma responses\n    logger.error(\"non-Chroma HTTP error: %s\", e)\n    raise","preventionTips":["Always include a plain-Exception handler after ChromaError when a proxy is in the path.","Log the raw body embedded in the message — it identifies which hop produced the error.","Set proxy read timeouts generously for large query/upsert payloads."],"tags":["chroma","http","error-mapping","proxy","gateway"],"backgroundTag":"http-error-status","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}