Too Many Parts Error or Parts Count >1000 on Any Table, ClickHouse

​

At a glance

The single most ClickHouse-distinctive alert in the set. It fires on either of two conditions: a TOO_MANY_PARTS error (code 252) has been thrown in the last 24 hours, or any MergeTree table is sitting above 1,000 active parts right now. Both point at the same failure mode: inserts have outrun background merges, the parts have piled up, and the parts cap is being hit. When that cap is reached, ClickHouse stops accepting inserts on that table entirely, so ingest halts. There is no equivalent in a traditional row store; it is unique to ClickHouse’s part-and-merge storage model, and it is the one failure a ClickHouse DBA must never miss.

​

Calculation

SELECT count() AS too_many_parts_24h
FROM system.query_log
WHERE type = 'ExceptionWhileProcessing'
  AND exception_code = 252            -- TOO_MANY_PARTS
  AND event_time >= now() - INTERVAL 24 HOUR

SELECT table, count() AS active_parts
FROM system.parts
WHERE active
GROUP BY table
HAVING active_parts > 1000
ORDER BY active_parts DESC

​

Worked example

1. Ingest on clickstream_raw is already broken. 37 code-252 errors means 37 insert batches were rejected outright in the last day. Every rejected batch is storefront event data that did not land. The data gap is growing in real time.
2. The cause is the batch-size change. The errors began climbing the same evening as the ingest config ship. Smaller batches mean more parts per unit of data, the part count crossed the per-partition parts_to_throw_insert cap, and inserts started bouncing.
3. order_events is next. At 880 parts and climbing, it is on the same trajectory. If the root cause is not fixed, it breaches within the hour and a second table stops ingesting.

Immediate response:
  1. Confirm the gap: how much data is missing?
       SELECT max(event_time) FROM events.clickstream_raw   -- last row that landed
     Compare against storefront's last-known event time.
  2. Stop the bleeding: revert the batch-size change so inserts batch large again.
  3. Drain the backlog: raise background_pool_size to merge faster, OR
       OPTIMIZE TABLE events.clickstream_raw PARTITION '2026-04-18' FINAL
       (heavy; target the hot partition only, off-peak).
  4. Backfill: replay the rejected batches from the ingest buffer / source once
     part count drops back below the throw threshold.

1. Code 252 means data loss, not just an error. Unlike a slow query, a rejected insert drops data on the floor unless your pipeline buffers and retries. Treat every nonzero too_many_parts_24h as a potential data-gap incident and check what is missing.
2. The part-count condition is your early warning; use it. If you act while only the >1000 part condition is breached and the error count is still zero, you prevent the outage entirely. Once code 252 appears you are in recovery, not prevention.
3. The fix is almost always insert shape. Smaller batches, higher insert frequency, or a too-granular partition key. Batch larger, use async_insert, or coarsen the partition key. Tuning merges only buys time.

​

Sibling cards

​

Reconciling against the source

Check the error count and the live part count directly in clickhouse-client:

-- condition 1: errors in the last 24h
SELECT count() FROM system.query_log
WHERE exception_code = 252 AND event_time >= now() - INTERVAL 24 HOUR;

-- condition 2: tables over the part threshold
SELECT table, count() FROM system.parts WHERE active
GROUP BY table HAVING count() > 1000 ORDER BY count() DESC;

Read the live caps with SELECT name, value FROM system.merge_tree_settings WHERE name LIKE 'parts_to%'. Watch active merges draining the backlog in system.merges. On ClickHouse Cloud, all of these system tables are available in the SQL console; the managed monitoring view also flags part-count and ingest-error conditions.

​

Known limitations / FAQs

​

Tracked live in Vortex IQ Nerve Centre