{"record":{"id":"5ad15355888de060","repo":"chroma-core/chroma","slug":"failed-to-get-embeddings-from-chroma-cloud-api-e","errorCode":null,"errorMessage":"Failed to get embeddings from Chroma Cloud API: {e}","messagePattern":"Failed to get embeddings from Chroma Cloud API: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/chroma_cloud_splade_embedding_function.py","lineNumber":110,"sourceCode":"            \"target\": \"\",\n            \"fetch_tokens\": \"true\" if self.include_tokens is True else \"false\",\n        }\n\n        try:\n            import httpx\n\n            response = self._session.post(self._api_url, json=payload, timeout=60)\n            response.raise_for_status()\n            json_response = response.json()\n            return self._parse_response(json_response)\n        except httpx.HTTPStatusError as e:\n            raise RuntimeError(\n                f\"Failed to get embeddings from Chroma Cloud API: HTTP {e.response.status_code} - {e.response.text}\"\n            )\n        except httpx.TimeoutException:\n            raise RuntimeError(\"Request to Chroma Cloud API timed out after 60 seconds\")\n        except httpx.HTTPError as e:\n            raise RuntimeError(f\"Failed to get embeddings from Chroma Cloud API: {e}\")\n        except Exception as e:\n            raise RuntimeError(f\"Unexpected error calling Chroma Cloud API: {e}\")\n\n    def _parse_response(self, response: Any) -> SparseVectors:\n        \"\"\"\n        Parse the response from the Chroma Cloud Sparse Embedding API.\n        \"\"\"\n        raw_embeddings = response[\"embeddings\"]\n\n        # Normalize each sparse vector (sort indices and validate)\n        normalized_vectors: SparseVectors = []\n        for emb in raw_embeddings:\n            # Handle both dict format and SparseVector format\n            if isinstance(emb, dict):\n                indices = emb.get(\"indices\", [])\n                values = emb.get(\"values\", [])\n                raw_labels = emb.get(\"labels\") if self.include_tokens else None\n                labels: Optional[List[str]] = raw_labels if raw_labels else None","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/chroma_cloud_splade_embedding_function.py#L92-L128","documentation":"The generic httpx.HTTPError except clause catches transport-level failures that are neither an HTTP status error nor a timeout — connection refused, DNS resolution failure, TLS errors, protocol problems — and re-raises them as RuntimeError with the original httpx message appended.","triggerScenarios":"Calling ef(texts) when the embed endpoint host cannot be reached: DNS failure resolving the API host, connection refused/reset, proxy misconfiguration, TLS certificate errors, or the httpx.Client being closed.","commonSituations":"Corporate proxies or firewalls blocking api.trychroma.com; air-gapped environments; custom embed URL overrides pointing at a dead host; calling ef after __del__/close() already closed the session; transient network drops.","solutions":["Read the appended httpx error: '[Errno -2] Name resolution failure' means DNS, 'Connection refused' means the host/proxy is wrong or down.","Verify network egress to the embed URL (get_chroma_embed_url default host) with curl.","Configure proxy/CA-bundle env vars (HTTPS_PROXY, SSL_CERT_FILE) if a corporate proxy intercepts traffic.","Retry with backoff for transient resets; do not reuse an EF whose close() was called."],"exampleFix":"# before\nvecs = ef([\"hello\"])  # RuntimeError: Failed ... [Errno -2] Name resolution failure\n\n# after: fail fast with a clear network check, then retry transient errors\nimport socket, httpx\nhost = \"api.trychroma.com\"  # host behind get_chroma_embed_url()\nsocket.gethostbyname(host)  # raises early if DNS is broken\ntry:\n    vecs = ef([\"hello\"])\nexcept RuntimeError as e:\n    if \"Connection reset\" not in str(e):\n        raise\n    vecs = ef([\"hello\"])  # one retry for transient reset","handlingStrategy":"try-catch","validationCode":"import httpx, socket\nfrom chromadb.utils.embedding_functions.utils import get_chroma_embed_url\n\nurl = get_chroma_embed_url()\nsocket.gethostbyname(httpx.URL(url).host)  # fail fast on DNS problems\n# egress check (loopback-only environments will refuse): skip in offline tests\n# httpx.get(url, timeout=5)  -> any HTTPError here explains the later failure","typeGuard":null,"tryCatchPattern":"try:\n    vecs = ef(texts)\nexcept RuntimeError as e:\n    msg = str(e)\n    if \"Name resolution\" in msg or \"Connection refused\" in msg:\n        raise ConnectionError(f\"Cannot reach embed endpoint: {msg}\") from e\n    if \"reset\" in msg.lower():\n        return ef(texts)  # single retry for transient reset\n    raise","preventionTips":["Verify DNS/egress to the embed URL in environment setup scripts.","Configure HTTPS_PROXY/SSL_CERT_FILE for corporate networks up front.","Never call a closed embedding function — share one instance and close it only at shutdown."],"tags":["chroma-cloud","splade","network","connection-error","sparse-embeddings"],"backgroundTag":"http-request-failed","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}