{"record":{"id":"5420b8064ddd3878","repo":"chroma-core/chroma","slug":"unknown-error","errorCode":null,"errorMessage":"Unknown error","messagePattern":"Unknown error","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/chroma_cloud_qwen_embedding_function.py","lineNumber":97,"sourceCode":"        self._session.headers.update(\n            {\n                \"x-chroma-token\": self.api_key,\n                \"x-chroma-embedding-model\": self.model.value,\n            }\n        )\n\n    def _parse_response(self, response: Any) -> Embeddings:\n        \"\"\"\n        Convert the response from the Chroma Embedding API to a list of numpy arrays.\n\n        Args:\n            response (Any): The response from the Chroma Embedding API.\n\n        Returns:\n            Embeddings: A list of numpy arrays representing the embeddings.\n        \"\"\"\n        if \"embeddings\" not in response:\n            raise RuntimeError(response.get(\"error\", \"Unknown error\"))\n\n        embeddings: List[List[float]] = response[\"embeddings\"]\n\n        return [np.array(embedding, dtype=np.float32) for embedding in embeddings]\n\n    def __call__(self, input: Documents) -> Embeddings:\n        \"\"\"\n        Generate embeddings for the given documents.\n\n        Args:\n            input: Documents to generate embeddings for.\n\n        Returns:\n            Embeddings for the documents.\n        \"\"\"\n        if not input:\n            return []\n","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/chroma_cloud_qwen_embedding_function.py#L79-L115","documentation":"_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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Read the message: it is the API's own error text (or 'Unknown error'), so it pinpoints auth vs model vs quota problems.","Verify the API key is current — regenerate and re-export CHROMA_API_KEY, then restart the process so headers are rebuilt.","Confirm the model header: the function must be built with a valid ChromaCloudQwenEmbeddingModel enum value (Qwen/Qwen3-Embedding-0.6B).","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."],"exampleFix":"# before\nembeddings = ef([\"hello world\"])  # RuntimeError: Unknown error\n\n# after\ntry:\n    embeddings = ef([\"hello world\"])\nexcept RuntimeError as e:\n    # message is the API error body; surface it instead of guessing\n    raise RuntimeError(f\"Chroma embed API error: {e}\") from e","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    embeddings = ef(texts)\nexcept RuntimeError as e:\n    msg = str(e)\n    # message is the API's error text, or 'Unknown error' for an unshaped payload\n    if \"token\" in msg.lower() or \"auth\" in msg.lower():\n        refresh_api_key_and_rebuild_ef()\n    else:\n        raise RuntimeError(f\"Chroma embed API rejected request: {msg}\") from e","preventionTips":["Smoke-test one embed call at startup to surface auth/model issues before batch jobs run.","Keep the API key fresh — regenerate and restart long-lived processes on rotation.","Log the full RuntimeError message; it carries the server's own explanation."],"tags":["chroma-cloud","qwen","api-error","embedding-function","runtime"],"backgroundTag":"api-error-response","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}