clickhouse-common-errors

name	clickhouse-common-errors
description	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".
allowed-tools	Read, Grep, Bash(curl:*)
version	1.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","database","analytics","clickhouse","olap"]
compatibility	Designed for Claude Code

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.query_log, system.columns, system.replicas).
• The failing statement's text and, ideally, the raw exception string — the parenthetical name (e.g. MEMORY_LIMIT_EXCEEDED) 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 MEMORY_LIMIT_EXCEEDED 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.query_log) 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:

-- Check current part count per table
SELECT database, table, count()  part_count
 system.parts  active   database,    part_count ;


 events MODIFY SETTING parts_to_throw_insert  ;