n8n-io/n8n · error · NodeApiError

Cannot connect to ChromaDB. Please ensure ChromaDB is runnin

Error message

Cannot connect to ChromaDB. Please ensure ChromaDB is running and accessible at the configured URL.

What it means

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.

Source

Thrown at packages/@n8n/nodes-langchain/nodes/vector_store/VectorStoreChromaDB/VectorStoreChromaDB.node.ts:361

				try {
					const client = await getChromaClient(this);
					const collections = await client.listCollections();

					if (Array.isArray(collections)) {
						const results = collections.map((collection: Collection) => ({
							name: collection.name,
							value: collection.name,
						}));
						return { results };
					}

					return { results: [] };
				} catch (error) {
					const errorMessage = error instanceof Error ? error.message : String(error);

					// Check for connection errors
					if (errorMessage.includes('ECONNREFUSED') || errorMessage.includes('Failed to connect')) {
						throw new NodeApiError(this.getNode(), {
							message:
								'Cannot connect to ChromaDB. Please ensure ChromaDB is running and accessible at the configured URL.',
						});
					}

					// Check for authentication errors
					if (
						errorMessage.includes('Unauthorized') ||
						errorMessage.includes('401') ||
						errorMessage.includes('403')
					) {
						throw new NodeApiError(this.getNode(), {
							message:
								'Authentication failed. Please check your API key or token in the credentials',
						});
					}

					throw new NodeApiError(this.getNode(), {

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Start the ChromaDB server (`docker run -p 8000:8000 chromadb/chroma`) and confirm with `curl http://<host>:<port>/api/v1/heartbeat`.
2. 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).
3. If behind a proxy, verify the proxy is up and the configured URL uses the right protocol/port.
4. Check that nothing between n8n and ChromaDB (firewall, security group, sidecar) is refusing the connection.

Example fix

// before: only ECONNREFUSED / 'Failed to connect' are treated as connection errors
if (errorMessage.includes('ECONNREFUSED') || errorMessage.includes('Failed to connect')) {
  throw new NodeApiError(this.getNode(), { message: 'Cannot connect to ChromaDB...' });
}

// after: also cover ENOTFOUND, ETIMEDOUT, and fetch-level network failures
const connectionHints = ['ECONNREFUSED', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN', 'Failed to connect', 'fetch failed'];
if (connectionHints.some((h) => errorMessage.includes(h))) {
  throw new NodeApiError(this.getNode(), {
    message: 'Cannot connect to ChromaDB. Please ensure ChromaDB is running and accessible at the configured URL.',
    description: `Underlying error: ${errorMessage}`,
  });
}

// Before the node runs, validate reachability of the configured URL in the credential.
async function assertChromaReachable(url: string, signal?: AbortSignal) {
  const res = await fetch(`${url.replace(/\/$/, '')}/api/v1/heartbeat`, { signal });
  if (!res.ok) throw new Error(`Chroma heartbeat returned ${res.status}`);
  return true;
}
// Call during credential save or node setup; surface a clear message before listCollections.

function isConnectionError(error: unknown): boolean {
  if (!(error instanceof Error)) return false;
  return ['ECONNREFUSED', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN', 'Failed to connect', 'fetch failed']
    .some((h) => error.message.includes(h));
}

try {
  return await chromaClient.listCollections();
} catch (error) {
  if (isConnectionError(error)) {
    throw new NodeApiError(node, { message: 'Cannot connect to ChromaDB. Please ensure ChromaDB is running and accessible at the configured URL.' });
  }
  throw error;
}

When it happens

Trigger: 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`.

Common situations: 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`.

Related errors

• Authentication failed. Please check your API key or token in
• Failed to list ChromaDB collections: ${errorMessage}
• Chroma getOrCreateCollection error: ${message}
• Failed to initialize Chroma collection
• Collection must be a string

AI-assisted analysis of n8n-io/n8n@5ac6606e81 (2026-08-12). Data as JSON: /api/errors/758e799090f81c77. Report an issue: GitHub.