chroma-core/chroma · error · RuntimeError

Failed to get embeddings from Chroma Cloud API: {e}

Error message

Failed to get embeddings from Chroma Cloud API: {e}

What it means

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.

Source

Thrown at chromadb/utils/embedding_functions/chroma_cloud_splade_embedding_function.py:110

            "target": "",
            "fetch_tokens": "true" if self.include_tokens is True else "false",
        }

        try:
            import httpx

            response = self._session.post(self._api_url, json=payload, timeout=60)
            response.raise_for_status()
            json_response = response.json()
            return self._parse_response(json_response)
        except httpx.HTTPStatusError as e:
            raise RuntimeError(
                f"Failed to get embeddings from Chroma Cloud API: HTTP {e.response.status_code} - {e.response.text}"
            )
        except httpx.TimeoutException:
            raise RuntimeError("Request to Chroma Cloud API timed out after 60 seconds")
        except httpx.HTTPError as e:
            raise RuntimeError(f"Failed to get embeddings from Chroma Cloud API: {e}")
        except Exception as e:
            raise RuntimeError(f"Unexpected error calling Chroma Cloud API: {e}")

    def _parse_response(self, response: Any) -> SparseVectors:
        """
        Parse the response from the Chroma Cloud Sparse Embedding API.
        """
        raw_embeddings = response["embeddings"]

        # Normalize each sparse vector (sort indices and validate)
        normalized_vectors: SparseVectors = []
        for emb in raw_embeddings:
            # Handle both dict format and SparseVector format
            if isinstance(emb, dict):
                indices = emb.get("indices", [])
                values = emb.get("values", [])
                raw_labels = emb.get("labels") if self.include_tokens else None
                labels: Optional[List[str]] = raw_labels if raw_labels else None

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. Read the appended httpx error: '[Errno -2] Name resolution failure' means DNS, 'Connection refused' means the host/proxy is wrong or down.
  2. Verify network egress to the embed URL (get_chroma_embed_url default host) with curl.
  3. Configure proxy/CA-bundle env vars (HTTPS_PROXY, SSL_CERT_FILE) if a corporate proxy intercepts traffic.
  4. Retry with backoff for transient resets; do not reuse an EF whose close() was called.

Example fix

# before
vecs = ef(["hello"])  # RuntimeError: Failed ... [Errno -2] Name resolution failure

# after: fail fast with a clear network check, then retry transient errors
import socket, httpx
host = "api.trychroma.com"  # host behind get_chroma_embed_url()
socket.gethostbyname(host)  # raises early if DNS is broken
try:
    vecs = ef(["hello"])
except RuntimeError as e:
    if "Connection reset" not in str(e):
        raise
    vecs = ef(["hello"])  # one retry for transient reset
Defensive patterns

Strategy: try-catch

Validate before calling

import httpx, socket
from chromadb.utils.embedding_functions.utils import get_chroma_embed_url

url = get_chroma_embed_url()
socket.gethostbyname(httpx.URL(url).host)  # fail fast on DNS problems
# egress check (loopback-only environments will refuse): skip in offline tests
# httpx.get(url, timeout=5)  -> any HTTPError here explains the later failure

Try / catch

try:
    vecs = ef(texts)
except RuntimeError as e:
    msg = str(e)
    if "Name resolution" in msg or "Connection refused" in msg:
        raise ConnectionError(f"Cannot reach embed endpoint: {msg}") from e
    if "reset" in msg.lower():
        return ef(texts)  # single retry for transient reset
    raise

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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