clickhouse-js-node-troubleshooting
Troubleshoot connection issues and timeouts with ClickHouse Node client.
Developer Setup
Setup & Installation
npx skills add https://github.com/ClickHouse/agent-skills --skill clickhouse-js-node-troubleshootingnpx skills add https://github.com/ClickHouse/agent-skills --skill clickhouse-js-node-troubleshootingOverview
What This Skill Does
Guides resolution of socket hang-ups, Keep-Alive issues, stream timeouts, and proxy errors in ClickHouse Node applications.
Application
When to use this Skill
- Resolving socket hang-up and connection timeout errors in Node.js.
- Configuring TCP Keep-Alive parameters for long-running database requests.
- Debugging stream handling or data type mismatches on the client side.
- Managing read-only user credentials or connection proxy boundaries.
- Troubleshooting random query connection drops and SSL/TLS handshakes.
Documentation
Show Skills.md file
ClickHouse Node.js Client Troubleshooting
Reference: https://clickhouse.com/docs/integrations/javascript
⚠️ Node.js runtime only. This skill covers the
@clickhouse/clientpackage running in a Node.js runtime exclusively — including Next.js Node runtime API routes, React Server Components, Server Actions, and standard Node.js processes. Do not apply this skill to browser client components, Web Workers, Next.js Edge runtime, Cloudflare Workers, or any usage of@clickhouse/client-web. For browser/edge environments, the correct package is@clickhouse/client-web.
How to Use This Skill
- Identify the issue — match symptoms to the Issue Index below and read the corresponding reference file.
- Lead with the diagnosis — explain what's likely causing the issue before giving the fix.
- Note version constraints — flag if a fix requires a minimum client version and check it against what the user provided.
- Ask only what's missing — if the fix is version-dependent and you don't know their version, ask; otherwise help immediately.
Issue Index
Identify the user's issue from the list below and read the corresponding reference file for detailed troubleshooting steps.
| Issue | Symptoms | Reference file |
|---|---|---|
| Socket Hang-Up / ECONNRESET | socket hang up, ECONNRESET, intermittent connection drops, long-running queries timing out |
reference/socket-hangup.md |
| Data Type Mismatches | Large integers returned as strings, decimal precision loss, Date/DateTime insertion failures | reference/data-types.md |
Recommendations