{"record":{"id":"455269b6c130a9ef","repo":"chroma-core/chroma","slug":"failed-to-connect-to-chroma","errorCode":null,"errorMessage":"Failed to connect to Chroma","messagePattern":"Failed to connect to Chroma","errorType":"exception","errorClass":"ChromaConnectionError","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/chroma-fetch.ts","lineNumber":56,"sourceCode":"\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(\n        `Bad request to ${\n          (input as Request).url || \"Chroma\"\n        } with status: ${status}`,\n      );","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/chroma-fetch.ts#L38-L74","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Reproduce the raw fetch to see the real cause: `await fetch(url)` in the same environment and inspect the underlying error.","For TLS issues, use a properly signed certificate or configure the CA (e.g. NODE_EXTRA_CA_CERTS); avoid disabling validation in production.","Fix the URL scheme/host (https vs http, correct port) in the client path.","For proxy/timeout issues, configure the proxy agent or raise undici timeouts."],"exampleFix":"// before\nconst client = new ChromaClient({ path: \"https://chroma.internal:8000\" }); // self-signed cert => generic ChromaConnectionError\n\n// after: trust the internal CA\n// NODE_EXTRA_CA_CERTS=/path/to/internal-ca.pem node app.js\nconst client = new ChromaClient({ path: \"https://chroma.internal:8000\" });","handlingStrategy":"try-catch","validationCode":"try {\n  await fetch(url, { method: \"GET\" });\n} catch (raw) {\n  console.error(\"raw fetch failure:\", raw); // inspect TLS/proxy/URL cause before blaming Chroma\n}","typeGuard":null,"tryCatchPattern":"try {\n  await client.heartbeat();\n} catch (e) {\n  if (e instanceof ChromaConnectionError) {\n    // generic transport failure: reproduce with bare fetch() to surface the underlying\n    // TypeError (TLS, proxy, invalid URL) — chromadb masks it as \"Failed to connect to Chroma\"\n  }\n  throw e;\n}","preventionTips":["Validate the URL scheme and host before constructing the client.","Trust custom CAs via NODE_EXTRA_CA_CERTS instead of ad-hoc workarounds.","Log the raw fetch error in a wrapper to preserve the root cause."],"tags":["network","tls","proxy","fetch","connection"],"backgroundTag":"http-request-failed","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}