Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Quick reference for the most common ClickHouse errors with real error codes,
diagnostic queries, and proven solutions.
Prerequisites
Access to ClickHouse (client or HTTP interface)
Ability to query system.* tables
Error Reference
1. Too Many Parts (Code 252)
DB::Exception: Too many parts (600). Merges are processing significantly slower than inserts.
Cause: Each INSERT creates a new data part. Hundreds of tiny inserts per second
overwhelm the merge process.
Fix:
-- Check current part count per tableSELECT database, table, count() AS part_count
FROM system.parts WHERE active GROUPBY database, tableORDERBY part_count DESC;
-- Temporary: raise the limitALTER TABLE events MODIFY SETTING parts_to_throw_insert =1000;
-- Permanent: batch your inserts (10K+ rows per INSERT)-- See clickhouse-sdk-patterns for batching code
-- Option C: Enable disk spill for large sorts/GROUP BY
SET
=
10000000000
SET
=
10000000000
3. Syntax Error (Code 62)
DB::Exception: Syntax error: ... Expected ... before ... (SYNTAX_ERROR)
Common causes:
-- Wrong: using backticks for identifiers (MySQL habit)SELECT `user_id` FROM events;
-- Fix: use double-quotes or no quotesSELECT "user_id" FROM events;
SELECT user_id FROM events;
-- Wrong: LIMIT with OFFSET keywordSELECT*FROM events LIMIT 10, 20;
-- Fix: use LIMIT ... OFFSETSELECT*FROM events LIMIT 10OFFSET20;
-- Wrong: using != in older versionsWHERE status !='active';
-- Fix: use <>WHERE status <>'active';
4. Unknown Table (Code 60)
DB::Exception: Table default.events does not exist. (UNKNOWN_TABLE)
Fix:
-- List all tables in the databaseSHOW TABLES FROMdefault;
-- Check all databasesSHOW DATABASES;
-- The table might be in a different databaseSELECT database, name FROM system.tables WHERE name LIKE'%events%';
5. Timeout Exceeded (Code 159)
DB::Exception: Timeout exceeded: elapsed ... seconds, max ... (TIMEOUT_EXCEEDED)
Fix:
-- Increase timeout for this querySET max_execution_time =120; -- seconds-- Find slow queries in historySELECT
query,
query_duration_ms,
read_rows,
result_rows,
memory_usage
FROM system.query_log
WHERE type ='QueryFinish'ORDERBY query_duration_ms DESC
LIMIT 10;
-- ClickHouse expects: YYYY-MM-DD HH:MM:SS-- Wrong: ISO 8601 with T and ZINSERT INTO events (created_at) VALUES ('2025-01-15T10:30:00Z');
-- Fix: strip T and ZINSERT INTO events (created_at) VALUES ('2025-01-15 10:30:00');
-- Or parse it explicitlySELECT parseDateTimeBestEffort('2025-01-15T10:30:00Z');
7. Readonly Mode (Code 164)
DB::Exception: ... is in readonly mode (READONLY)
Cause: User lacks write permissions or server is in readonly mode.
Fix:
-- Check user permissionsSHOW GRANTS FORCURRENT_USER;
-- Check server settingSELECT name, valueFROM system.settings WHERE name ='readonly';
-- Currently running queriesSELECT query_id, user, query, elapsed, read_rows, memory_usage
FROM system.processes;
-- Kill a stuck query
KILL QUERY WHERE query_id ='abc-123';
-- Recent errors from query logSELECT event_time, query, exception_code, exception
FROM system.query_log
WHERE type ='ExceptionWhileProcessing'ORDERBY event_time DESC
LIMIT 20;
-- Disk usage by tableSELECT
database, table,
formatReadableSize(sum(bytes_on_disk)) AS size,
sum(rows) AS total_rows,
count() AS parts
FROM system.parts WHERE active
GROUPBY database, tableORDERBYsum(bytes_on_disk) DESC;
-- Merge healthSELECT database, table, progress, elapsed, num_parts
FROM system.merges;
