Agent skill · data analytics · jeremylongshore
clickhouse-common-errors
Diagnose and fix the top 15 ClickHouse errors — query failures, insert problems, memory limits, and merge issues. Use when a ClickHouse query or insert throws an exception, a server-side error appears in logs, or a failed query needs root-cause analysis. Trigger with "clickhouse error", "fix clickhouse", "clickhouse not working", "debug clickhouse", "clickhouse exception", "clickhouse syntax error".
Why this skill is useful
Provides specific diagnostic queries and solutions for common ClickHouse errors that the AI wouldn't reliably generate on its own.
What it needs
About 3k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
ClickHouse Common Errors Overview Quick reference for the most common ClickHouse errors with real error codes, diagnostic queries, and proven solutions. The three highest-frequency errors are inline below; the full catalog of 10 errors plus system-table diagnostics lives in references/error-reference.md. Prerequisites Access to a ClickHouse endpoint — either the native clickhouse-client or the HTTP interface (curl against :8123). Permission to read the system. introspection tables (system.parts, system.processes, system.querylog, system.columns, system.replicas). The failing statement's text and, ideally, the raw exception string — the parenthetical name (e.g. MEMORYLIMITEXCEEDED) and numeric code drive lookup. Instructions Follow this loop to turn a raw ClickHouse exception into a verified fix: 1. Capture the exception name and code. Read the error string the client returned. If you only have a log file, use Grep to pull the matching line — Grep for DB::Exception or a specific token like MEMORYLIMITEXCEEDED across the log to isolate the failure. 2. Map it to a category. Use the Error Handling code table to classify the error as Schema, Query, Performance, Permissions, Concurrency, Resources, or Insert-pattern. 3. Apply the inline fix for the three top errors (Too Many Parts, Memory Limit, Syntax) below, or open references/error-reference.md for the other seven plus copy-paste diagnostic queries. 4. Confirm with a system table. Re-run the relevant system. query (part count, system.processes, system.querylog) to prove the condition cleared rather than assuming the fix took. Top 3 errors (inline) Too Many Parts (Code 252) — hundreds of tiny inserts outpace merges: Memory Limit Exceeded (Code 241) — query wants more RAM than maxmemoryusage: Syntax Error (Code 62) — most often MySQL habits leaking in: See references/error-reference.md for Unknown Table, Timeout, DateTime parsing, Readonly, No Such Column, Type Mismatch, and Distributed-table errors. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/clickhouse-common-errors