Diagnose Clickhouse Errors
Maps a ClickHouse error code to a per-code diagnosis playbook and a 3-section Cause/Fix answer
Test report
- Verdict
- Works with setup
- Score
- Tested
- Jul 21, 2026
- Environment
- Claude Code 2.x (agent harness)
- Upstream re-checked
- Aug 10, 2026 · e25f75c
GitHub API was rate-limited, so I cloned the repo and found SKILL.md at resources/skills/diagnose-clickhouse-errors/; raw-fetched SKILL.md, references/60.md and references/342.md (all HTTP 200; a made-up references/999.md returned 404, confirming only 5 codes ship), grep found no curl|sh, base64, credentials or injection text, and I ran the install block in a throwaway HOME=$(mktemp -d) where it placed SKILL.md plus all 5 reference files correctly. Trigger phrasings I judged: SHOULD fire — "My query failed with Code: 60. DB::Exception: Table analytics.evnts doesn't exist. (UNKNOWN_TABLE), what's wrong?", "ClickHouse throws error code 115 on my SETTINGS clause, how do I fix it?", "Getting NUMBER_OF_ARGUMENTS_DOESNT_MATCH from toStartOfInterval in ClickHouse"; SHOULD NOT — "This ClickHouse query takes 40 seconds, help me speed it up" (optimization, not a failure) and "Our Java service logs a ClickHouse UNKNOWN_TABLE error, find where in our repo the table name is built" (the description and a When-Not-To-Use section explicitly hand that to source-code-inspection); 5/5 correct. Output test used error 342 because references/342.md is the only playbook not requiring the missing execute_sql tool: the baseline named the missing `payload` column, gave read-only checks (system.replicas, clusterAllReplicas over system.columns) and three remediation options including `SYSTEM DROP REPLICA ... FROM TABLE events.page_views_local`, while the skill-followed run collapsed to ~180 words with headings ## Cause / ## Fix, the mandated stored/parsed/local fragment extraction, zero mutating commands and "escalate to the cluster maintainer / SRE" — safer for a prod incident but strictly less actionable for a Claude Code user who is the maintainer, so I scored it no better than baseline. Verdict setup: for 4 of the 5 codes the evidence step is a live `execute_sql` I could not execute, and three tool names in the body (skill_resource, execute_sql, ask_user_question) are DataStoria product internals that no README or skill note flags as unavailable outside that app.
Scored on four weighted criteria — install, triggering, output vs. baseline, docs. How scoring works
- Installs cleanly 5/5
- Triggers reliably 5/5
- Output vs. baseline 5/10
- Docs & honesty 3/5
What Diagnose Clickhouse Errors does
Turns a ClickHouse runtime error into a fixed Cause / Fix / Example answer by extracting the numeric error code and loading a per-code playbook (42, 47, 60, 115, 342 are bundled). Triggers when a user pastes a DB::Exception or names a ClickHouse error code and wants database-level cause and fix guidance, and explicitly defers to source-code inspection when the goal is finding where the failing SQL was built. Most playbooks expect a live ClickHouse to run a system.columns / system.tables / system.settings lookup, with a documented text-only fallback when that query cannot run.
How to install Diagnose Clickhouse Errors
git clone --depth 1 https://github.com/FrankChen021/datastoria.git /tmp/diagnose-clickhouse-errors-src
mkdir -p ~/.claude/skills
cp -R /tmp/diagnose-clickhouse-errors-src/resources/skills/diagnose-clickhouse-errors ~/.claude/skills/diagnose-clickhouse-errors
# Verified: places SKILL.md + references/{42,47,60,115,342}.md under ~/.claude/skills/diagnose-clickhouse-errors/
# The repo is the DataStoria web console (~large clone); only this one directory is needed.
# Sibling skills in the same folder that this one references: source-code-inspection, optimize-clickhouse-sql,
# clickhouse-system-queries, diagnose-clickhouse-clusters, sql-expert, visualization.
# MANUAL STEP: the skill body calls DataStoria-internal tools that do not exist in Claude Code:
# skill_resource -> read references/<code>.md yourself
# ask_user_question -> AskUserQuestion
# execute_sql -> needs a ClickHouse MCP server or a clickhouse-client you run by hand;
# without it, codes 42/47/60/115 fall back to text-only diagnosis (documented in each file).
Skills live in ~/.claude/skills/ (global) or .claude/skills/
(per-project). Restart Claude Code after installing.
Commands — how to trigger Diagnose Clickhouse Errors
-
/diagnose-clickhouse-errorsMaps a ClickHouse error code to a per-code diagnosis playbook and a 3-section Cause/Fix answer
It also activates on plain-language prompts like these:
-
Diagnose this ClickHouse error code 241 -
Why did my ClickHouse query fail at runtime -
Explain this ClickHouse memory limit exceeded error
Frequently asked questions
- Is the Diagnose Clickhouse Errors skill free?
- Yes. The skill itself is free from FrankChen021/datastoria. SkillProof publishes the install command and an independent test verdict at no cost.
- Does Diagnose Clickhouse Errors work with Claude Code?
- We tested it with Claude Code 2.x (agent harness) on Jul 21, 2026. Verdict: Works with setup. GitHub API was rate-limited, so I cloned the repo and found SKILL.md at resources/skills/diagnose-clickhouse-errors/; raw-fetched SKILL.md, references/60.md and references/342.md (all HTTP 200; a made-up references/999.md returned 404, confirming only 5 codes ship), grep found no curl|sh, base64, credentials or injection text, and I ran the install block in a throwaway HOME=$(mktemp -d) where it placed SKILL.md plus all 5 reference files correctly. Trigger phrasings I judged: SHOULD fire — "My query failed with Code: 60. DB::Exception: Table analytics.evnts doesn't exist. (UNKNOWN_TABLE), what's wrong?", "ClickHouse throws error code 115 on my SETTINGS clause, how do I fix it?", "Getting NUMBER_OF_ARGUMENTS_DOESNT_MATCH from toStartOfInterval in ClickHouse"; SHOULD NOT — "This ClickHouse query takes 40 seconds, help me speed it up" (optimization, not a failure) and "Our Java service logs a ClickHouse UNKNOWN_TABLE error, find where in our repo the table name is built" (the description and a When-Not-To-Use section explicitly hand that to source-code-inspection); 5/5 correct. Output test used error 342 because references/342.md is the only playbook not requiring the missing execute_sql tool: the baseline named the missing `payload` column, gave read-only checks (system.replicas, clusterAllReplicas over system.columns) and three remediation options including `SYSTEM DROP REPLICA ... FROM TABLE events.page_views_local`, while the skill-followed run collapsed to ~180 words with headings ## Cause / ## Fix, the mandated stored/parsed/local fragment extraction, zero mutating commands and "escalate to the cluster maintainer / SRE" — safer for a prod incident but strictly less actionable for a Claude Code user who is the maintainer, so I scored it no better than baseline. Verdict setup: for 4 of the 5 codes the evidence step is a live `execute_sql` I could not execute, and three tool names in the body (skill_resource, execute_sql, ask_user_question) are DataStoria product internals that no README or skill note flags as unavailable outside that app.
- What is the Diagnose Clickhouse Errors SkillProof Score?
- 7.2/10 — installs cleanly 5/5, triggers reliably 5/5, output vs. baseline 5/10, docs & honesty 3/5.
- How do I install Diagnose Clickhouse Errors?
- Copy the install command from this page, run it in your terminal, and restart Claude Code. Skills live in ~/.claude/skills/ (global) or .claude/skills/ inside a project.
- Can I use Diagnose Clickhouse Errors with Cursor, Copilot, Gemini CLI, Codex or other AI tools?
- The SKILL.md format is native to Claude (Claude Code, Desktop, claude.ai). The instructions inside adapt to other assistants: Cursor rules, GitHub Copilot instructions, Windsurf rules, Custom GPTs, AGENTS.md for OpenAI Codex, and GEMINI.md for Google Gemini CLI — our conversion guides cover each, and the free converter on the tools page does the wrapping for you.