{"record":{"id":"0e941b9c311d8599","repo":"chroma-core/chroma","slug":"failed-to-connect-to-chromadb-make-sure-your-serv-0e941b","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"exception","errorClass":"ChromaConnectionError","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/chroma-fetch.ts","lineNumber":52,"sourceCode":"  } catch {\n    return {};\n  }\n};\n\nconst getErrorMessage = async (response: Response): Promise<string> => {\n  const body = await getErrorBody(response);\n  return (\n    body.message || body.error || `${response.status}: ${response.statusText}`\n  );\n};\n\nexport const chromaFetch: typeof fetch = async (input, init) => {\n  let response: Response;\n  try {\n    response = await fetch(input, init);\n  } catch (err) {\n    if (offlineError(err)) {\n      throw new ChromaConnectionError(\n        \"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.\",\n      );\n    }\n    throw new ChromaConnectionError(\"Failed to connect to Chroma\");\n  }\n\n  if (response.ok) {\n    return response;\n  }\n\n  switch (response.status) {\n    case 400:\n      let status = \"Bad Request\";\n      try {\n        const responseBody = await response.json();\n        status = responseBody.message || status;\n      } catch {}\n      throw new ChromaClientError(","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/chroma-fetch.ts#L34-L70","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before: server not running / wrong origin\nconst client = new ChromaClient({ path: \"http://localhoost:8000\" }); // typo\n\n# after\nconst client = new ChromaClient({ path: \"http://localhost:8000\" });\n# and on the server (browser clients):\nCHROMA_SERVER_CORS_ALLOW_ORIGINS='[\"http://localhost:5173\"]' chroma run --path ./data","handlingStrategy":"try-catch","validationCode":"async function serverReachable(url: string): Promise<boolean> {\n  try {\n    const res = await fetch(`${url.replace(/\\/$/, \"\")}/api/v2/heartbeat`);\n    return res.ok;\n  } catch { return false; }\n}\nif (!(await serverReachable(clientPath))) throw new Error(\"Chroma server unreachable at \" + clientPath);","typeGuard":null,"tryCatchPattern":"try {\n  await client.heartbeat();\n} catch (e) {\n  if (e instanceof ChromaConnectionError && e.message.includes(\"Make sure your server is running\")) {\n    // offline/CORS/DNS: check server process, URL, and CHROMA_SERVER_CORS_ALLOW_ORIGINS\n  }\n  throw e;\n}","preventionTips":["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."],"tags":["network","connection","cors","dns","server-not-running"],"backgroundTag":"connection-refused","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}