{"record":{"id":"efb6ed08515e9485","repo":"cube-js/cube","slug":"connection-check-failed-errormessage","errorCode":null,"errorMessage":"Connection check failed: ${errorMessage}","messagePattern":"Connection check failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/cubejs-clickhouse-driver/src/ClickHouseDriver.ts","lineNumber":222,"sourceCode":"    this.client = this.createClient(maxPoolSize);\n  }\n\n  protected withCancel<T>(fn: (con: ClickHouseClient, queryId: string, signal: AbortSignal) => Promise<T>): Promise<T> {\n    const queryId = uuidv4();\n\n    const abortController = new AbortController();\n    const { signal } = abortController;\n\n    const promise = (async () => {\n      const pingResult = await this.client.ping();\n      if (!pingResult.success) {\n        // TODO replace string formatting with proper cause\n        // pingResult.error can be AggregateError when ClickHouse hostname resolves to multiple addresses\n        let errorMessage = pingResult.error.toString();\n        if (pingResult.error instanceof AggregateError) {\n          errorMessage = `Aggregate error: ${pingResult.error.message}; errors: ${pingResult.error.errors.join('; ')}`;\n        }\n        throw new Error(`Connection check failed: ${errorMessage}`);\n      }\n      signal.throwIfAborted();\n      // Queries sent by `fn` can hit a timeout error, would _not_ get killed, and continue running in ClickHouse\n      // TODO should we kill those as well?\n      const result = await fn(this.client, queryId, signal);\n      signal.throwIfAborted();\n      return result;\n    })();\n    (promise as any).cancel = async () => {\n      abortController.abort();\n      // Use separate client for kill query, usual pool may be busy\n      const killClient = this.createClient(1);\n      try {\n        await killClient.command({\n          query: `KILL QUERY WHERE query_id = '${queryId}'`,\n        });\n      } finally {\n        await killClient.close();","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-clickhouse-driver/src/ClickHouseDriver.ts#L204-L240","documentation":"ClickHouseDriver.withCancel pings the ClickHouse server through @clickhouse/client before executing the wrapped query/callback. If the ping fails, the driver wraps the ping error (stringified, with special handling for AggregateError when the hostname resolves to multiple addresses) and throws 'Connection check failed: <error>'. It aborts before running user SQL so queries don't hit a dead connection.","triggerScenarios":"query(), command(), or insert() calls when the initial ping to the ClickHouse host fails: server down, wrong host/port, TLS mismatch, DNS failure, or unreachable network from the container.","commonSituations":"ClickHouse container not started in docker-compose; wrong ClickHouseDriver host/port/protocol options; AggregateError when the hostname resolves to multiple IPs (e.g. headless service in k8s) with some unreachable; firewall blocking the native HTTP port 8123.","solutions":["Check the wrapped message: for AggregateError, look at the per-address errors to see which IP/cause failed","Verify ClickHouse is reachable: curl http://<host>:8123/ping from the Cube process host","Correct driver config (host, port, protocol http/https, username/password) in the constructor options","Fix DNS/load-balancer so the resolved address is reachable, or pin a single resolvable address"],"exampleFix":"// before\nconst driver = new ClickHouseDriver({ host: 'http://clickhouse:8443' }); // wrong port/protocol\n// after\nconst driver = new ClickHouseDriver({ host: 'https://clickhouse:8443' });","handlingStrategy":"retry","validationCode":"// Pre-flight reachability check\nconst res = await fetch(`${host}/ping`).catch(() => null);\nif (!res || !res.ok) {\n  throw new Error(`ClickHouse unreachable at ${host}; check server/port/protocol`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await cube.query(query);\n} catch (e) {\n  if (e.message.startsWith('Connection check failed:')) {\n    if (e.message.includes('Aggregate error')) {\n      // multi-address DNS issue: inspect per-address errors\n    }\n    // retry with backoff or fail fast on startup\n  }\n}","preventionTips":["Add a startup health check against /ping before serving traffic","Use a single stable hostname/IP for the ClickHouse endpoint","Match protocol (http vs https) to the actual server port"],"tags":["clickhouse","network","connection"],"backgroundTag":"connection-refused","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}