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;
