chroma-core/chroma · error · ValueError

Chroma error response missing required 'message' field: {res

Error message

Chroma error response missing required 'message' field: {resp.text} (trace ID: {trace_id})

What it means

Raised by BaseHTTPClient._raise_chroma_error while converting a failing HTTP response into an exception. The response body parsed as JSON and contained an "error" key (so it looked like a Chroma error envelope) but lacked the required "message" key, raising KeyError. This means the server — or something rewriting its responses — produced a malformed Chroma-style error payload.

Source

Thrown at chromadb/api/base_http_client.py:142

                ):
                    chroma_error = errors.ConditionalWriteConflictError(message)
                elif error_name in errors.error_types:
                    chroma_error = errors.error_types[error_name](message)

                if chroma_error is not None:
                    trace_id = resp.headers.get("chroma-trace-id")
                    if trace_id:
                        chroma_error.trace_id = trace_id

        except KeyError as e:
            message = (
                "Chroma error response missing required 'message' field: "
                f"{resp.text}"
            )
            trace_id = resp.headers.get("chroma-trace-id")
            if trace_id:
                message = f"{message} (trace ID: {trace_id})"
            raise ValueError(message) from e
        except BaseException:
            pass

        if chroma_error:
            raise chroma_error

        try:
            resp.raise_for_status()
        except httpx.HTTPStatusError:
            trace_id = resp.headers.get("chroma-trace-id")
            if trace_id:
                raise Exception(f"{resp.text} (trace ID: {trace_id})")
            raise (Exception(resp.text))

    def get_request_headers(self) -> Mapping[str, str]:
        """Return headers used for HTTP requests."""
        return {}

View on GitHub (pinned to aecdd12c8a)

Solutions

Read the raw response body embedded in the message — it shows exactly what was returned and by whom.
Pin client and server to matching chromadb versions.
Disable or fix any middleware/proxy that rewrites error response bodies.
If a trace ID is present in the message, use it to locate the corresponding server log entry.

Defensive patterns

Strategy: try-catch

Try / catch

try:
    client.list_collections()
except ValueError as e:
    if "missing required 'message' field" in str(e):
        # malformed Chroma error envelope — inspect raw body in the message,
        # then check version skew / response-rewriting middleware
        logger.error("malformed server error body: %s", e)
    raise

Prevention

Run the same chromadb version on client and server.
Do not put middleware in front of Chroma that rewrites error bodies.
In tests, mock error responses with the full {error, message} envelope.

When it happens

Trigger: A server/middleware version that emits {"error": "..."} without "message"; a proxy or custom middleware that rewrites Chroma error bodies; a hand-rolled stub server in tests returning a partial envelope; a Chroma server version whose error schema differs from the client's.

Common situations: Client and server chromadb versions skew (upgraded one but not the other); sidecars mutating error responses; test mocks returning incomplete error JSON.

Related errors

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