skilld
All skills
clickhouse avatar

/clickhouse-js-node-troubleshooting

@faa5b11 official
by clickhouseclickhouse/agent-skills543 stars
39

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.

Ask your Agent

Use this Skill: https://skilld.dev/gh/clickhouse/agent-skills/clickhouse-js-node-troubleshooting

This session only. Nothing lands on disk.

referencecompression.md

≈364 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Compression Not Working

Applies to: all versions. Response compression was enabled by default in < 1.0.0 and disabled by default since >= 1.0.0 — you must explicitly enable it. Request compression has always been opt-in.

Both request and response compression are supported. Only GZIP is supported (via zlib).

import { createClient } from "@clickhouse/client";
const client = createClient({
  compression: {
    response: true,
    request: true,
  },
});

Compression enabled but getting an error?

If you enable compression.response: true and get a ClickHouse settings error, you are likely connecting as a readonly=1 user. Response compression requires the enable_http_compression setting, which read-only users cannot change.

See reference/readonly-users.md for the fix.

Compression enabled but response doesn't seem compressed?

  • Verify your version-specific defaults — response compression was enabled by default in < 1.0.0 and is disabled by default in >= 1.0.0, so on newer versions you must enable compression.response: true explicitly.
  • Check that the ClickHouse server has HTTP compression enabled (enable_http_compression = 1 in server config). By default this is enabled on ClickHouse Cloud and most self-hosted setups.
  • Request compression (compression.request: true) compresses the request body sent to ClickHouse. It has no effect on the response.

Source: SKILL.md on GitHub

Third-party checks

No alerts17d3 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    This skill provides comprehensive troubleshooting documentation for the ClickHouse Node.js client. It includes security best practices, such as using parameterized queries to prevent SQL injection and clear warnings against insecure TLS configurations in production environments. No malicious patterns or security risks were detected.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

Provenance

Signed by skilld at faa5b11. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 3 months ago

Topics

  • clickhouse
  • nodejs
  • troubleshooting
  • client
  • socket
  • tls
  • compression
  • data-types
  • connection

README badge

README badge for clickhouse/agent-skills/clickhouse-js-node-troubleshooting

What it does

Diagnose and resolve common issues with the ClickHouse Node.js client (@clickhouse/client), including socket hang-ups, data type mismatches, TLS configuration problems, compression failures, and read-only user restrictions. Applies only to Node.js runtime environments, not browser or edge runtimes.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with the browser/Web client or just Node.js?
This skill covers only the Node.js runtime (@clickhouse/client), including Next.js Node API routes and Server Actions. For browser, Edge runtime, Cloudflare Workers, or Web Worker environments, use @clickhouse/client-web instead.
What kinds of errors does this skill help troubleshoot?
Socket hang-ups, ECONNRESET, data type mismatches, read-only user restrictions, proxy/TLS setup, compression issues, query timeouts, and query parameter interpolation problems with the ClickHouse Node.js client.
Do I need to know the exact error message to use this skill?
No. Vague symptoms like 'my inserts keep failing' or 'connection drops randomly' in a Node.js context are strong enough signals to trigger this skill.
Will this skill help with version compatibility issues?
Yes. The skill flags if a fix requires a minimum client version and will ask for your version if it's needed to recommend the right solution.

Generated from the current SKILL.md. These answers refresh after source changes.