Clickhouse Js Node Troubleshooting

作者 ClickHouse2f6ec4b17a81无许可证544 个星标收录于 2026年10月8日更新于 2026年10月8日仓库9天前更新

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.

仅含说明Software Development
AI 生成的概览

排查并解决 ClickHouse Node.js 客户端（@clickhouse/client）的常见错误与配置问题。

功能
该技能把用户报告的 ClickHouse Node.js 客户端症状对应到九个参考文件，涵盖 socket hang-up、数据类型不匹配、只读用户、代理路径名混淆、TLS、压缩、日志、查询参数以及 FORMAT 子句错误。它引导智能体先给出诊断再给出修复方案，标注版本限制，并只询问缺失的信息。产出是排查建议与解释，而不是代码改动或文件。
适用场景
当用户报告涉及 ClickHouse Node.js 客户端的错误、异常行为或配置问题时使用，包括插入失败、连接随机中断等模糊症状。仅适用于 Node.js 运行时（含 Next.js Node 运行时），不适用于浏览器、边缘运行时或 @clickhouse/client-web。
运行要求
无需脚本，仅包含说明与参考 Markdown 文件。对于依赖版本的修复，智能体需要用户提供客户端版本，并可能查阅外部 ClickHouse 文档链接。

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.

IssueSymptomsReference file
Socket Hang-Up / ECONNRESETsocket hang up, ECONNRESET, intermittent connection drops, long-running queries timing outreference/socket-hangup.md
Data Type MismatchesLarge integers returned as strings, decimal precision loss, Date/DateTime insertion failures, CANNOT_PARSE_INPUT_ASSERTION_FAILED inserting a UUID into a UInt128 columnreference/data-types.md
Read-Only User ErrorsErrors when using response compression with readonly=1 usersreference/readonly-users.md
Proxy / Pathname URL ConfusionWrong database selected, requests failing behind a proxy with a path prefixreference/proxy-pathname.md
TLS / Certificate ErrorsTLS handshake failures, certificate verification issues, mutual TLS setupreference/tls.md
Compression Not WorkingGZIP compression not activating for requests or responsesreference/compression.md
Logging Not Showing AnythingNo log output, need custom logger integrationreference/logging.md
Query Parameters Not InterpolatedParameterized queries not working, SQL injection concernsreference/query-params.md
FORMAT Clause / SHOW POLICIES ErrorsSyntax error from a duplicate FORMAT, or SHOW [ROW] POLICIES failing even with a format providedreference/query-format-clause.md

Still Stuck?

来源与署名

来源：ClickHouse/agent-skills位于skills/clickhouse-js-node-troubleshooting提交2f6ec4b

许可证： 无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 ClickHouse/agent-skills 的技能

Clickhouse Managed Postgres Rca

ClickHouse

针对 ClickHouse 托管 Postgres 实例性能问题的基于证据的根因分析工作流。

DevOps & Cloud5449天前更新

Clickhouse Best Practices

ClickHouse

依据 31 条最佳实践规则审查 ClickHouse 的模式、查询与写入策略。

Data & Analytics5449天前更新

Clickhouse Architecture Advisor

ClickHouse

针对特定工作负载指导 ClickHouse 架构决策，并将每条建议标注为官方、推导或经验。

Data & Analytics5449天前更新

Chdb Sql

ClickHouse

Use when the user wants to run SQL — especially analytical SQL — on local files (parquet/csv/json), URLs, S3 paths, or remote databases (Postgres, MySQL, MongoDB, ClickHouse Cloud, Iceberg, Delta Lake) without setting up a server. Provides chDB — embedded ClickHouse SQL in Python with 1000+ functions, Session for stateful multi-step pipelines, parametrized queries, and cross-source joins via `s3()`, `mysql()`, `postgresql()`, `iceberg()`, `deltaLake()`, `remoteSecure()` table functions. TRIGGER when: user wants SQL on parquet/csv/files or across remote analytical sources; uses ClickHouse SQL features (window functions, windowFunnel, geoToH3, JSON path ops, Session, parametrized queries); imports `chdb` or calls `chdb.query()`. SKIP this skill for pandas-style DataFrame method-chaining (use chdb-datastore instead) or ClickHouse server administration.

包含脚本
待分类5449天前更新

Chdb Datastore

ClickHouse

使用 chdb DataStore 作为 pandas 的替代方案，基于 ClickHouse 查询、连接和聚合表格数据。

包含脚本
Data & Analytics5449天前更新

更多Software Development技能

Playground

anthropics

精选

构建自包含的交互式 HTML 演练场，包含控件、实时预览和可复制的提示词输出。

Software Development37K今天更新

M5 Onboard

anthropics

精选

通过 USB 检测 M5Stack ESP32 开发板，刷写 UIFlow 2.0 固件并安装 MicroPython 应用包。

Software Development37K今天更新

Cardputer Buddy

anthropics

精选

指导迭代 Cardputer-Adv 的 MicroPython 应用包：添加应用、通过 USB 串口推送文件、查看日志并运行 REPL 命令。

Software Development37K今天更新

Dpop Adoption

google

精选

指导为 Google OAuth 平台实现 OAuth 2.0 DPoP（RFC 9449）发送方约束刷新令牌。

Software Development21K今天更新

Gemini Live Api

google

精选

生成 Gemini Live API WebSocket 客户端类、测试、文档和用于双向流式传输的演示界面。

Software Development21K今天更新

Gemini Api

google

精选

指导如何在 Google Agent Platform 上使用 Gen AI SDK 调用 Gemini API，涵盖多语言与多项能力。

Software Development21K今天更新