# Clickhouse Js Node Troubleshooting

Troubleshoot and resolve common issues with the ClickHouse Node.js client...

- Repository: https://github.com/ClickHouse/agent-skills (565 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add ClickHouse/agent-skills --skill clickhouse-js-node-troubleshooting -g -a claude-code -y`
Codex: `npx skills add ClickHouse/agent-skills --skill clickhouse-js-node-troubleshooting -g -a codex -y`
Cursor: `npx skills add ClickHouse/agent-skills --skill clickhouse-js-node-troubleshooting -g -a cursor -y`
Gemini CLI: `npx skills add ClickHouse/agent-skills --skill clickhouse-js-node-troubleshooting -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add ClickHouse/agent-skills`

## Description

Troubleshoot and resolve common issues with the ClickHouse Node.js client (@clickhouse/client). Use this skill whenever a user reports errors, unexpected behavior, or configuration questions involving the Node.js client specifically, including socket hang-up errors, Keep-Alive problems, stream handling issues, data type mismatches, read-only user restrictions, proxy/TLS setup problems, or long-running query timeouts. Trigger even when the user hasn't precisely named the issue; vague symptoms like "my inserts keep failing" or "connection drops randomly" in a Node.js context are strong signals to use this skill. Do NOT use for browser/Web client issues.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# ClickHouse Node.js Client Troubleshooting

Reference: https://clickhouse.com/docs/integrations/javascript

> **⚠️ Node.js runtime only.** This skill covers the `@clickhouse/client` package 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

1. **Identify the issue**, match symptoms to the Issue Index below and read the corresponding reference file.
2. **Lead with the diagnosis**, explain what's likely causing the issue before giving the fix.
3. **Note version constraints**, flag if a fix requires a minimum client version and check it against what the user provided.
4. **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.

The rest: https://github.com/ClickHouse/agent-skills/blob/HEAD/skills/clickhouse-js-node-troubleshooting/SKILL.md