{"record":{"id":"758e799090f81c77","repo":"n8n-io/n8n","slug":"cannot-connect-to-chromadb-please-ensure-chromadb","errorCode":null,"errorMessage":"Cannot connect to ChromaDB. Please ensure ChromaDB is running and accessible at the configured URL.","messagePattern":"Cannot connect to ChromaDB\\. Please ensure ChromaDB is running and accessible at the configured URL\\.","errorType":"exception","errorClass":"NodeApiError","httpStatus":null,"severity":"error","filePath":"packages/@n8n/nodes-langchain/nodes/vector_store/VectorStoreChromaDB/VectorStoreChromaDB.node.ts","lineNumber":361,"sourceCode":"\t\t\t\ttry {\n\t\t\t\t\tconst client = await getChromaClient(this);\n\t\t\t\t\tconst collections = await client.listCollections();\n\n\t\t\t\t\tif (Array.isArray(collections)) {\n\t\t\t\t\t\tconst results = collections.map((collection: Collection) => ({\n\t\t\t\t\t\t\tname: collection.name,\n\t\t\t\t\t\t\tvalue: collection.name,\n\t\t\t\t\t\t}));\n\t\t\t\t\t\treturn { results };\n\t\t\t\t\t}\n\n\t\t\t\t\treturn { results: [] };\n\t\t\t\t} catch (error) {\n\t\t\t\t\tconst errorMessage = error instanceof Error ? error.message : String(error);\n\n\t\t\t\t\t// Check for connection errors\n\t\t\t\t\tif (errorMessage.includes('ECONNREFUSED') || errorMessage.includes('Failed to connect')) {\n\t\t\t\t\t\tthrow new NodeApiError(this.getNode(), {\n\t\t\t\t\t\t\tmessage:\n\t\t\t\t\t\t\t\t'Cannot connect to ChromaDB. Please ensure ChromaDB is running and accessible at the configured URL.',\n\t\t\t\t\t\t});\n\t\t\t\t\t}\n\n\t\t\t\t\t// Check for authentication errors\n\t\t\t\t\tif (\n\t\t\t\t\t\terrorMessage.includes('Unauthorized') ||\n\t\t\t\t\t\terrorMessage.includes('401') ||\n\t\t\t\t\t\terrorMessage.includes('403')\n\t\t\t\t\t) {\n\t\t\t\t\t\tthrow new NodeApiError(this.getNode(), {\n\t\t\t\t\t\t\tmessage:\n\t\t\t\t\t\t\t\t'Authentication failed. Please check your API key or token in the credentials',\n\t\t\t\t\t\t});\n\t\t\t\t\t}\n\n\t\t\t\t\tthrow new NodeApiError(this.getNode(), {","sourceCodeStart":343,"sourceCodeEnd":379,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/nodes-langchain/nodes/vector_store/VectorStoreChromaDB/VectorStoreChromaDB.node.ts#L343-L379","documentation":"Thrown as a NodeApiError inside the `chromaCollection` resource locator's `listSearch` handler when the caught error message contains `ECONNREFUSED` or `Failed to connect`. It tells the user the n8n node cannot open a TCP connection to the configured ChromaDB URL. The check is pure string matching on the underlying error message rather than error-class introspection.","triggerScenarios":"Opening the collection dropdown in the node UI (which fires `listCollections`) while the ChromaDB server is down, while the URL/host/port is wrong, or while a firewall/DNS issue refuses the connection; the underlying axios/fetch error message bubbles up containing `ECONNREFUSED`.","commonSituations":"ChromaDB container not started; URL set to `localhost:8000` but Chroma is on a different port; Docker networking means `localhost` from the n8n container points at the n8n container, not the host; TLS-terminated proxy returning a connection reset that the SDK reports as `Failed to connect`.","solutions":["Start the ChromaDB server (`docker run -p 8000:8000 chromadb/chroma`) and confirm with `curl http://<host>:<port>/api/v1/heartbeat`.","Correct the collection's URL field in the node to the reachable address (use the service name, not `localhost`, when n8n itself runs in Docker).","If behind a proxy, verify the proxy is up and the configured URL uses the right protocol/port.","Check that nothing between n8n and ChromaDB (firewall, security group, sidecar) is refusing the connection."],"exampleFix":"// before: only ECONNREFUSED / 'Failed to connect' are treated as connection errors\nif (errorMessage.includes('ECONNREFUSED') || errorMessage.includes('Failed to connect')) {\n  throw new NodeApiError(this.getNode(), { message: 'Cannot connect to ChromaDB...' });\n}\n\n// after: also cover ENOTFOUND, ETIMEDOUT, and fetch-level network failures\nconst connectionHints = ['ECONNREFUSED', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN', 'Failed to connect', 'fetch failed'];\nif (connectionHints.some((h) => errorMessage.includes(h))) {\n  throw new NodeApiError(this.getNode(), {\n    message: 'Cannot connect to ChromaDB. Please ensure ChromaDB is running and accessible at the configured URL.',\n    description: `Underlying error: ${errorMessage}`,\n  });\n}","handlingStrategy":"validation","validationCode":"// Before the node runs, validate reachability of the configured URL in the credential.\nasync function assertChromaReachable(url: string, signal?: AbortSignal) {\n  const res = await fetch(`${url.replace(/\\/$/, '')}/api/v1/heartbeat`, { signal });\n  if (!res.ok) throw new Error(`Chroma heartbeat returned ${res.status}`);\n  return true;\n}\n// Call during credential save or node setup; surface a clear message before listCollections.","typeGuard":"function isConnectionError(error: unknown): boolean {\n  if (!(error instanceof Error)) return false;\n  return ['ECONNREFUSED', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN', 'Failed to connect', 'fetch failed']\n    .some((h) => error.message.includes(h));\n}","tryCatchPattern":"try {\n  return await chromaClient.listCollections();\n} catch (error) {\n  if (isConnectionError(error)) {\n    throw new NodeApiError(node, { message: 'Cannot connect to ChromaDB. Please ensure ChromaDB is running and accessible at the configured URL.' });\n  }\n  throw error;\n}","preventionTips":["Run a heartbeat check (`/api/v1/heartbeat`) when saving the Chroma credential.","Use service DNS names rather than `localhost` when n8n runs in Docker.","Add a health-check sidecar for ChromaDB so it is up before n8n starts."],"tags":["chromadb","vector-store","network","connection-error","node-api-error","langchain"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}