chroma-core/chroma · error · ChromaConnectionError

Failed to connect to chromadb. Make sure your server is runn

Error message

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.

What it means

Thrown by chromaFetch (chroma-fetch.ts:52) as a ChromaConnectionError when the underlying fetch rejects with an offline-shaped error (TypeError/FetchError containing 'fetch failed', 'Failed to fetch', or 'ENOTFOUND' per the offlineError heuristic). It means the HTTP request never reached a Chroma server: the process is offline, DNS could not resolve the host, the server is down, or (in browsers) CORS blocked the request.

Source

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

  } catch {
    return {};
  }
};

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(

View on GitHub (pinned to aecdd12c8a)

Solutions

Start or verify the Chroma server (e.g. `chroma run --path ./chroma-data`) and confirm it responds at the configured URL (curl http://localhost:8000/api/v2/heartbeat).
Check the client path/URL for typos and correct host/port, especially inside Docker/Kubernetes where 'localhost' is not the server.
For browser clients, set CHROMA_SERVER_CORS_ALLOW_ORIGINS on the server to include your page's origin.
If DNS-related (ENOTFOUND), fix hostname resolution or use an IP/service name that resolves.

Example fix

# before: server not running / wrong origin
const client = new ChromaClient({ path: "http://localhoost:8000" }); // typo

# after
const client = new ChromaClient({ path: "http://localhost:8000" });
# and on the server (browser clients):
CHROMA_SERVER_CORS_ALLOW_ORIGINS='["http://localhost:5173"]' chroma run --path ./data

Defensive patterns

Strategy: try-catch

Validate before calling

async function serverReachable(url: string): Promise<boolean> {
  try {
    const res = await fetch(`${url.replace(/\/$/, "")}/api/v2/heartbeat`);
    return res.ok;
  } catch { return false; }
}
if (!(await serverReachable(clientPath))) throw new Error("Chroma server unreachable at " + clientPath);

Try / catch

try {
  await client.heartbeat();
} catch (e) {
  if (e instanceof ChromaConnectionError && e.message.includes("Make sure your server is running")) {
    // offline/CORS/DNS: check server process, URL, and CHROMA_SERVER_CORS_ALLOW_ORIGINS
  }
  throw e;
}

Prevention

Add a startup health check (heartbeat) with a clear failure message before doing work.
For browser apps, configure CHROMA_SERVER_CORS_ALLOW_ORIGINS to the exact origin(s).
In containers, address the server by service name, never localhost.

When it happens

Trigger: Any API call (heartbeat, listCollections, createCollection, ...) while the Chroma server is stopped, the path URL has a typo/unresolvable host, a firewall drops the connection, or in a browser when the Chroma server did not allow the page's origin via CHROMA_SERVER_CORS_ALLOW_ORIGINS.

Common situations: Forgetting to run `chroma run` before starting the app; pointing ChromaClient at http://localhost:8000 in a container where the server is on another host; browser-based apps hitting a Chroma instance without CORS configuration; DNS/VPN issues in CI.

Related errors

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