What causes "Unexpected error calling Chroma Cloud API: {e}" in chroma-core/chroma?

Inspect the text after 'Unexpected error:' — it names the real underlying exception (e.g. JSONDecodeError, KeyError).

chroma-core/chroma · error · RuntimeError

Unexpected error calling Chroma Cloud API: {e}

Error message

Unexpected error calling Chroma Cloud API: {e}

What it means

The final except Exception clause in __call__ is a catch-all: anything that is not an httpx HTTPStatusError, TimeoutException, or HTTPError — malformed JSON in the response, KeyError/TypeError while parsing an unexpected payload, errors raised by _parse_response normalizing sparse vectors — is re-raised as RuntimeError prefixed with 'Unexpected error'. The original exception's text is preserved after the colon.

Source

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

        }

        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
            else:
                # Already a SparseVector, extract its data

View on GitHub (pinned to aecdd12c8a)

Solutions

Inspect the text after 'Unexpected error:' — it names the real underlying exception (e.g. JSONDecodeError, KeyError).
Reproduce the request manually (POST to the _api_url with the EF's headers) to inspect the raw body.
If a proxy is mangling responses, bypass or correctly configure it.
Report contract mismatches to Chroma with the raw payload; retry once in case of truncation.

Example fix

# before
vecs = ef(texts)  # RuntimeError: Unexpected error ... Expecting value: line 1 column 1 (char 0)

# after: distinguish parse failures from API errors
try:
    vecs = ef(texts)
except RuntimeError as e:
    msg = str(e)
    if msg.startswith("Unexpected error"):
        # log one raw request/response pair, then fail loudly
        raise RuntimeError(f"Unparseable /embed_sparse response: {msg}") from e
    raise

Defensive patterns

Strategy: try-catch

Try / catch

try:
    vecs = ef(texts)
except RuntimeError as e:
    if str(e).startswith("Unexpected error"):
        # underlying cause is appended after the colon (JSONDecodeError, KeyError, ...)
        logger.exception("Unparseable /embed_sparse response: %s", e)
        vecs = ef(texts)  # at most one retry for truncated bodies
    else:
        raise

Prevention

Log the full message — it preserves the original exception text after the prefix.
Keep proxies from rewriting API responses (verify with a manual curl of the same payload).
Pin your chromadb version so client/server contract changes surface in upgrades, not randomly.

When it happens

Trigger: Calling ef(texts) when the server replies 200 with a non-JSON or truncated body (response.json() raises), or with JSON whose 'embeddings' entries have an unexpected shape that breaks _parse_response/normalize_sparse_vector.

Common situations: Proxies or captive portals injecting HTML; truncated responses on flaky links; API contract changes on the Chroma Cloud side; payloads where sparse vectors contain duplicate or out-of-range indices.

Related errors

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