Diagnose Clickhouse Errors
Ordnet einen ClickHouse-Fehlercode einem Code-spezifischen Diagnose-Playbook und einer 3-teiligen Ursache/Lösung-Antwort zu
Funktioniert mit Setup
Was es kann
Wandelt einen ClickHouse-Laufzeitfehler in eine feste Ursache / Lösung / Beispiel-Antwort um, indem der numerische Fehlercode extrahiert und ein Code-spezifisches Playbook geladen wird (42, 47, 60, 115, 342 sind gebündelt). Wird ausgelöst, wenn ein Benutzer eine DB::Exception einfügt oder einen ClickHouse-Fehlercode nennt und datenbankbezogene Ursachen- und Lösungsanleitungen wünscht, und verweist explizit auf die Quellcode-Inspektion, wenn das Ziel darin besteht, herauszufinden, wo die fehlerhafte SQL erstellt wurde. Die meisten Playbooks erwarten ein Live-ClickHouse, um eine system.columns / system.tables / system.settings-Abfrage auszuführen, mit einem dokumentierten Nur-Text-Fallback, wenn diese Abfrage nicht ausgeführt werden kann.
Testbericht
GitHub API war ratenbegrenzt, daher habe ich das Repo geklont und SKILL.md unter resources/skills/diagnose-clickhouse-errors/ gefunden; SKILL.md, references/60.md und references/342.md roh abgerufen (alle HTTP 200; ein erfundener references/999.md lieferte 404, was bestätigt, dass nur 5 Codes ausgeliefert werden), grep fand keine curl|sh, base64, Credentials oder Injection-Text, und ich habe den Installationsblock in einem temporären HOME=$(mktemp -d) ausgeführt, wo er SKILL.md plus alle 5 Referenzdateien korrekt platzierte. Trigger-Formulierungen, die ich beurteilt habe: SOLLTE auslösen — „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“; SOLLTE NICHT — „This ClickHouse query takes 40 seconds, help me speed it up“ (Optimierung, keine Fehlfunktion) und „Our Java service logs a ClickHouse UNKNOWN_TABLE error, find where in our repo the table name is built“ (die Beschreibung und ein Abschnitt „When-Not-To-Use“ verweisen explizit auf die Quellcode-Inspektion); 5/5 korrekt. Der Output-Test verwendete Fehler 342, da references/342.md das einzige Playbook ist, das das fehlende execute_sql-Tool nicht benötigt: Die Baseline nannte die fehlende `payload`-Spalte, gab schreibgeschützte Prüfungen (system.replicas, clusterAllReplicas über system.columns) und drei Korrekturmöglichkeiten, einschließlich `SYSTEM DROP REPLICA ... FROM TABLE events.page_views_local`, während der Skill-befolgte Lauf auf ~180 Wörter mit Überschriften ## Cause / ## Fix, die vorgeschriebene Extraktion von gespeicherten/geparsten/lokalen Fragmenten, null mutierenden Befehlen und „escalate to the cluster maintainer / SRE“ zusammenbrach — sicherer für einen Produktionsvorfall, aber strikt weniger umsetzbar für einen Claude Code-Benutzer, der der Maintainer ist, daher habe ich es nicht besser als die Baseline bewertet. Urteil: Setup: Für 4 der 5 Codes ist der Evidenzschritt ein Live-`execute_sql`, den ich nicht ausführen konnte, und drei Tool-Namen im Body (skill_resource, execute_sql, ask_user_question) sind DataStoria-Produktinterna, die kein README oder Skill-Hinweis als außerhalb dieser App nicht verfügbar kennzeichnet.
Getestet am: 2026-07-21 · Claude Code 2.x (agent harness)
Installation
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). Befehle & Beispiel-Prompts
/diagnose-clickhouse-errorsOrdnet einen ClickHouse-Fehlercode einem Code-spezifischen Diagnose-Playbook und einer 3-teiligen Ursache/Lösung-Antwort zu
Skills reagieren auf normale Anfragen — keine Slash-Befehle nötig. Nach der Installation aktivieren Prompts wie diese den Skill (auf Englisch):
Diagnose this ClickHouse error code 241Why did my ClickHouse query fail at runtimeExplain this ClickHouse memory limit exceeded error