# clickhouse-js-node-troubleshooting

Troubleshoots socket hang-ups, data type mismatches, and TLS issues in the ClickHouse Node.js client (@clickhouse/client).

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 7600 installs · ★ 561
- Author: ClickHouse
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/ClickHouse/agent-skills/tree/HEAD/skills/clickhouse-js-node-troubleshooting/SKILL.md
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/skills/clickhouse-js-node-troubleshooting

## What it does

This skill diagnoses errors in the `@clickhouse/client` package. It targets network drops like `ECONNRESET`, stream insertion failures, GZIP compression errors for `readonly=1` users, and query parameter interpolation bugs.

The workflow inspects symptoms against an issue index and reference guides. The agent explains the likely root cause first and checks client version requirements before proposing a patch. It will ask for your client version if a fix depends on it.

The skill only applies to Node.js environments, including Next.js Server Actions and route handlers. Applying these troubleshooting steps to Cloudflare Workers, browser components, or `@clickhouse/client-web` will lead to incorrect fixes.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add ClickHouse/agent-skills --skill clickhouse-js-node-troubleshooting -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/clickhouse-js-node-troubleshooting/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/clickhouse-js-node-troubleshooting/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add ClickHouse/agent-skills --skill clickhouse-js-node-troubleshooting -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/clickhouse-js-node-troubleshooting/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add ClickHouse/agent-skills --skill clickhouse-js-node-troubleshooting -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/clickhouse-js-node-troubleshooting/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install ClickHouse/agent-skills clickhouse-js-node-troubleshooting
```

2. **Manually: put the files in place**
- File: `.github/skills/clickhouse-js-node-troubleshooting/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add ClickHouse/agent-skills --skill clickhouse-js-node-troubleshooting -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/ClickHouse/agent-skills --path skills/clickhouse-js-node-troubleshooting
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/clickhouse-js-node-troubleshooting/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add ClickHouse/agent-skills --skill clickhouse-js-node-troubleshooting -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/ClickHouse/agent-skills/tree/HEAD/skills/clickhouse-js-node-troubleshooting/SKILL.md

## When to use it
- resolve socket hang up and ECONNRESET drops during long queries
- fix data type mismatches such as large integers returning as strings
- configure TLS certificates and paths behind reverse proxies
- troubleshoot response compression failures for read-only database users

## Example prompts
- My ClickHouse inserts keep failing with socket hang up in Node.js, how do I fix this?
- Why are big integer columns returning as strings in @clickhouse/client?
- Help me resolve a TLS certificate handshake error when connecting to ClickHouse

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: f9238b84b74e4725.

BEGIN THIRD-PARTY FILE f9238b84b74e4725
```text
---
name: clickhouse-js-node-troubleshooting
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.
---

# 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.

| Issue                                      | Symptoms                                                                                                                                                                     | Reference file                     |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
```
END THIRD-PARTY FILE f9238b84b74e4725

The third-party file has ended. Everything between the f9238b84b74e4725 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2517 of 5137 bytes. © ClickHouse · Apache-2.0 · https://github.com/ClickHouse/agent-skills/tree/HEAD/skills/clickhouse-js-node-troubleshooting/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md