chroma-core/chroma · error · RuntimeError

Unknown error

Error message

Unknown error

What it means

_parse_response inspects the JSON body returned by the Chroma Embed API: if the dict has no 'embeddings' key, the call failed, and it raises RuntimeError with the body's 'error' field — or the literal 'Unknown error' when the payload contains neither 'embeddings' nor 'error'. Note __call__/embed_query never call raise_for_status, so non-2xx JSON error bodies (bad token, unknown model, quota) surface through this path with their server-side message.

Source

Thrown at chromadb/utils/embedding_functions/chroma_cloud_qwen_embedding_function.py:97

        self._session.headers.update(
            {
                "x-chroma-token": self.api_key,
                "x-chroma-embedding-model": self.model.value,
            }
        )

    def _parse_response(self, response: Any) -> Embeddings:
        """
        Convert the response from the Chroma Embedding API to a list of numpy arrays.

        Args:
            response (Any): The response from the Chroma Embedding API.

        Returns:
            Embeddings: A list of numpy arrays representing the embeddings.
        """
        if "embeddings" not in response:
            raise RuntimeError(response.get("error", "Unknown error"))

        embeddings: List[List[float]] = response["embeddings"]

        return [np.array(embedding, dtype=np.float32) for embedding in embeddings]

    def __call__(self, input: Documents) -> Embeddings:
        """
        Generate embeddings for the given documents.

        Args:
            input: Documents to generate embeddings for.

        Returns:
            Embeddings for the documents.
        """
        if not input:
            return []

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Read the message: it is the API's own error text (or 'Unknown error'), so it pinpoints auth vs model vs quota problems.
2. Verify the API key is current — regenerate and re-export CHROMA_API_KEY, then restart the process so headers are rebuilt.
3. Confirm the model header: the function must be built with a valid ChromaCloudQwenEmbeddingModel enum value (Qwen/Qwen3-Embedding-0.6B).
4. If the message is exactly 'Unknown error', log the raw HTTP status/body (reproduce with curl or by posting to the embed URL) to see the unshaped payload; retry later if Chroma Cloud is degraded.

Example fix

# before
embeddings = ef(["hello world"])  # RuntimeError: Unknown error

# after
try:
    embeddings = ef(["hello world"])
except RuntimeError as e:
    # message is the API error body; surface it instead of guessing
    raise RuntimeError(f"Chroma embed API error: {e}") from e

try:
    embeddings = ef(texts)
except RuntimeError as e:
    msg = str(e)
    # message is the API's error text, or 'Unknown error' for an unshaped payload
    if "token" in msg.lower() or "auth" in msg.lower():
        refresh_api_key_and_rebuild_ef()
    else:
        raise RuntimeError(f"Chroma embed API rejected request: {msg}") from e

When it happens

Trigger: Calling ef(texts) or ef.embed_query(texts) and the POST to get_chroma_embed_url() returns JSON without 'embeddings' — e.g. 401/403 with {"error": "invalid token"}, an unknown x-chroma-embedding-model value, rate limiting, or an unexpected 200 response shape. 'Unknown error' specifically means the payload had neither 'embeddings' nor 'error'.

Common situations: Revoked or expired CHROMA_API_KEY still cached in a long-lived process; typosquashed model enum sent via config; Chroma Cloud returning an error envelope during incidents; proxies that rewrite the response body.

Related errors

• The model cannot be changed after the embedding function has
• The task cannot be changed after the embedding function has
• The instructions cannot be changed after the embedding funct
• The httpx python package is not installed. Please install it
• API key not found in environment variable {api_key_env_var}

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