chroma-core/chroma · error · RuntimeError

Unknown error

Error message

Unknown error

What it means

__call__ posts to the API and parses the JSON body without checking the HTTP status, then expects the shape {'result': {'data': [...]}}. When the payload does not match, it raises RuntimeError with the response's 'detail' field, falling back to 'Unknown error' when the body has no detail key. Note the guard uses 'and', so this exact RuntimeError fires when 'result' exists but lacks 'data' (a body missing 'result' entirely surfaces as a KeyError instead) - in practice both indicate an error or unexpected body from a bad account_id, model_name, key, or gateway route.

Source

Thrown at chromadb/utils/embedding_functions/cloudflare_workers_ai_embedding_function.py:102

        Args:
            input: Documents to generate embeddings for.

        Returns:
            Embeddings for the documents.
        """
        if not all(isinstance(item, str) for item in input):
            raise ValueError(
                "Cloudflare Workers AI only supports text documents, not images"
            )

        payload: Dict[str, Any] = {
            "text": input,
        }

        resp = self._session.post(self._api_url, json=payload).json()

        if "result" not in resp and "data" not in resp["result"]:
            raise RuntimeError(resp.get("detail", "Unknown error"))

        return cast(Embeddings, resp["result"]["data"])

    @staticmethod
    def name() -> str:
        return "cloudflare_workers_ai"

    def default_space(self) -> Space:
        return "cosine"

    def supported_spaces(self) -> List[Space]:
        return ["cosine", "l2", "ip"]

    @staticmethod
    def build_from_config(config: Dict[str, Any]) -> "EmbeddingFunction[Documents]":
        api_key_env_var = config.get("api_key_env_var")
        model_name = config.get("model_name")
        account_id = config.get("account_id")

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Reproduce the raw request with httpx and print status_code and text to see the real API error - the function swallows the HTTP status.
2. Verify account_id, gateway_id (if used), and that model_name exists for your account (https://developers.cloudflare.com/workers-ai/models/).
3. Confirm the API key is current: curl the same endpoint with Authorization: Bearer $CLOUDFLARE_API_KEY and expect HTTP 200.
4. Wrap __call__ in try/except RuntimeError and log the exception before re-raising so production failures carry context.

Example fix

# before
embs = ef(['hello'])  # RuntimeError: Unknown error

# after (diagnose the underlying API response)
import httpx, os
key = os.getenv('CLOUDFLARE_API_KEY')
r = httpx.post(api_url, json={'text': ['hello']}, headers={'Authorization': f'Bearer {key}'})
print(r.status_code, r.text)  # e.g. 404 -> wrong account_id/model_name

import httpx, os

def cloudflare_preflight(api_url: str) -> None:
    key = os.getenv('CLOUDFLARE_API_KEY')
    r = httpx.post(api_url, json={'text': ['ping']}, headers={'Authorization': f'Bearer {key}'})
    if r.status_code != 200:
        raise RuntimeError(f'Workers AI preflight failed: {r.status_code} {r.text}')

try:
    embs = ef(texts)
except RuntimeError as e:
    logger.error('workers-ai embed failed: %s', e)
    raise
except KeyError:
    logger.error('workers-ai returned an error body without result/detail')
    raise

When it happens

Trigger: Calling ef(texts) when the POST returns an error or unexpected body: wrong account_id or non-existent @cf/... model_name in the URL, invalid/expired API key, wrong gateway_id, or rate limiting - with no 'detail' field in the JSON.

Common situations: Typos in account_id or model name; key rotated in the Cloudflare dashboard while the env var still holds the old value; account without Workers AI enabled; gateways/proxies returning a differently-shaped error that still parses as JSON.

Related errors

• resp.detail || "Unknown error"
• Invalid response format from Together AI API
• Chroma error response missing required 'message' field: {res
• {resp.text} (trace ID: {trace_id})
• Component not running

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