How do I install the Clickhouse JS Node Troubleshooting skill?

Run npx skillmds@latest add cline/clickhouse-js-node-troubleshooting in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Clickhouse JS Node Troubleshooting safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Clickhouse JS Node Troubleshooting?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Clickhouse JS Node Troubleshooting free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.

Who published Clickhouse JS Node Troubleshooting?

cline (@cline) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Clickhouse JS Node Troubleshooting by cline

Name: Clickhouse JS Node Troubleshooting
Author: cline

Clickhouse JS Node Troubleshooting

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.

cline 03e54b3 10 files · 24.0 KB Updated Sep 17, 2026

File contents

ClickHouse Node.js Client Troubleshooting

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

Warning 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

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`
Read-Only User Errors	Errors when using response compression with `readonly=1` users	`reference/readonly-users.md`
Proxy / Pathname URL Confusion	Wrong database selected, requests failing behind a proxy with a path prefix	`reference/proxy-pathname.md`
TLS / Certificate Errors	TLS handshake failures, certificate verification issues, mutual TLS setup	`reference/tls.md`
Compression Not Working	GZIP compression not activating for requests or responses	`reference/compression.md`
Logging Not Showing Anything	No log output, need custom logger integration	`reference/logging.md`
Query Parameters Not Interpolated	Parameterized queries not working, SQL injection concerns	`reference/query-params.md`

Still Stuck?

---name: clickhouse-js-node-troubleshootingdescription: 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.license: MIT---# ClickHouse Node.js Client TroubleshootingReference: https://clickhouse.com/docs/integrations/javascript> Warning 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 Skill1. 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 IndexIdentify 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` || Read-Only User Errors | Errors when using response compression with `readonly=1` users | `reference/readonly-users.md` || Proxy / Pathname URL Confusion | Wrong database selected, requests failing behind a proxy with a path prefix | `reference/proxy-pathname.md` || TLS / Certificate Errors | TLS handshake failures, certificate verification issues, mutual TLS setup | `reference/tls.md` || Compression Not Working | GZIP compression not activating for requests or responses | `reference/compression.md` || Logging Not Showing Anything | No log output, need custom logger integration | `reference/logging.md` || Query Parameters Not Interpolated | Parameterized queries not working, SQL injection concerns | `reference/query-params.md` |---## Still Stuck?- [JS client source + full examples](https://github.com/ClickHouse/clickhouse-js/tree/main/examples)- [ClickHouse JS client docs](https://clickhouse.com/docs/integrations/javascript)- [ClickHouse supported formats](https://clickhouse.com/docs/interfaces/formats)

Frequently asked questions