chroma-core/chroma · error · ChromaConnectionError

Failed to connect to Chroma

Error message

Failed to connect to Chroma

What it means

Thrown by chromaFetch (chroma-fetch.ts:56) as a generic ChromaConnectionError when the underlying fetch throws but the error does NOT match the offlineError heuristic (not a TypeError/FetchError with 'fetch failed'/'Failed to fetch'/'ENOTFOUND'). It signals a transport-level failure other than plain unreachability — e.g. TLS certificate problems, malformed request URLs, aborted requests, proxy errors, or Node fetch undici errors like UND_ERR_CONNECT_TIMEOUT.

Source

Thrown at clients/new-js/packages/chromadb/src/chroma-fetch.ts:56

const getErrorMessage = async (response: Response): Promise<string> => {
  const body = await getErrorBody(response);
  return (
    body.message || body.error || `${response.status}: ${response.statusText}`
  );
};

export const chromaFetch: typeof fetch = async (input, init) => {
  let response: Response;
  try {
    response = await fetch(input, init);
  } catch (err) {
    if (offlineError(err)) {
      throw new ChromaConnectionError(
        "Failed to connect to chromadb. Make sure your server is running and try again. If you are running from a browser, make sure that your chromadb instance is configured to allow requests from the current origin using the CHROMA_SERVER_CORS_ALLOW_ORIGINS environment variable.",
      );
    }
    throw new ChromaConnectionError("Failed to connect to Chroma");
  }

  if (response.ok) {
    return response;
  }

  switch (response.status) {
    case 400:
      let status = "Bad Request";
      try {
        const responseBody = await response.json();
        status = responseBody.message || status;
      } catch {}
      throw new ChromaClientError(
        `Bad request to ${
          (input as Request).url || "Chroma"
        } with status: ${status}`,
      );

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. Reproduce the raw fetch to see the real cause: `await fetch(url)` in the same environment and inspect the underlying error.
  2. For TLS issues, use a properly signed certificate or configure the CA (e.g. NODE_EXTRA_CA_CERTS); avoid disabling validation in production.
  3. Fix the URL scheme/host (https vs http, correct port) in the client path.
  4. For proxy/timeout issues, configure the proxy agent or raise undici timeouts.

Example fix

// before
const client = new ChromaClient({ path: "https://chroma.internal:8000" }); // self-signed cert => generic ChromaConnectionError

// after: trust the internal CA
// NODE_EXTRA_CA_CERTS=/path/to/internal-ca.pem node app.js
const client = new ChromaClient({ path: "https://chroma.internal:8000" });
Defensive patterns

Strategy: try-catch

Validate before calling

try {
  await fetch(url, { method: "GET" });
} catch (raw) {
  console.error("raw fetch failure:", raw); // inspect TLS/proxy/URL cause before blaming Chroma
}

Try / catch

try {
  await client.heartbeat();
} catch (e) {
  if (e instanceof ChromaConnectionError) {
    // generic transport failure: reproduce with bare fetch() to surface the underlying
    // TypeError (TLS, proxy, invalid URL) — chromadb masks it as "Failed to connect to Chroma"
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling any Chroma API where fetch itself throws: self-signed/expired TLS cert on an https Chroma endpoint, URL with an invalid scheme, request aborted mid-flight, undici socket/connect errors, or an HTTP proxy refusing the CONNECT.

Common situations: Self-hosted Chroma behind TLS with a self-signed certificate; corporate proxies intercepting traffic; https:// mismatch with a plain-HTTP server; Node 18+ undici timeout errors on slow links.

Related errors

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