ClickHouse DB::Exception: Bad data part name

The DB::Exception: Bad data part name error (code BAD_DATA_PART_NAME) occurs when ClickHouse encounters a data part whose name does not conform to the expected internal naming pattern. Part names encode partition information, block numbers, and merge levels, and any deviation from this format is rejected.

Impact

The operation that references the malformed part name fails immediately. This could be a table startup, an ALTER TABLE command referencing the part, or a replication fetch. If the bad name exists as a directory on disk, ClickHouse may refuse to load the table until the offending directory is removed or renamed.

Common Causes

Manual creation or renaming of directories inside the ClickHouse data folder that do not follow the part naming convention.
Corrupted filesystem metadata that garbled a directory name.
Incompatible ClickHouse version upgrade where the part naming scheme changed (rare, but possible between major versions).
Partial restore from backup that placed directories with incorrect names into the data folder.
Specifying an invalid part name in an ALTER TABLE command (e.g., typo in an ATTACH PART or DROP DETACHED PART statement).

Troubleshooting and Resolution Steps

Identify the problematic part name Check the ClickHouse error log for the exact name that failed validation. The log entry will show the rejected name.
Understand the naming convention ClickHouse part names follow the format:
```
partition_id_min_block_max_block_level
```
For example: 202301_1_5_2 means partition 202301, blocks 1 through 5, merge level 2.
Look for rogue directories on disk
```
ls /var/lib/clickhouse/data/db/my_table/
```
Identify any directory names that do not match the expected pattern.
Move invalid directories to detached If an invalid directory is preventing table load:
```
mv /var/lib/clickhouse/data/db/my_table/bad_name \
   /var/lib/clickhouse/data/db/my_table/detached/bad_name
```
Then restart ClickHouse. The table should load without the offending part.
Fix the part name in ALTER TABLE commands If you mistyped a part name in a SQL command, verify the correct name:
```
SELECT name FROM system.parts WHERE table = 'my_table' AND active;
SELECT name FROM system.detached_parts WHERE table = 'my_table';
```
Use the exact name from the output.
Check for version compatibility If the error appeared after an upgrade, review the ClickHouse changelog for changes to part naming. You may need to let the server convert old parts during startup.

Best Practices

Never manually create, rename, or move directories inside the ClickHouse data folder; use SQL commands for all part management.
When scripting part operations, always query system.parts or system.detached_parts for exact part names rather than constructing them by hand.
Test major version upgrades in a staging environment to catch any part format incompatibilities.
Keep backups of the data directory before performing manual recovery operations.
Use ATTACH PARTITION rather than ATTACH PART when you do not need to target a specific part, as it is less error-prone.

Frequently Asked Questions

Q: Can I rename a directory to fix the part name?
A: Technically yes, but you need to know the correct naming format and ensure internal metadata files match. It is generally safer to let ClickHouse recreate the part via replication.

Q: Will ClickHouse skip bad-named parts automatically?
A: No. A part directory with an invalid name in the active data folder will prevent the table from loading. You must move it to the detached directory or remove it.

Q: Does this error happen with non-replicated MergeTree tables too?
A: Yes. Part naming conventions apply to all MergeTree family engines, not just replicated ones.

Q: What should I do with the invalid part after moving it to detached?
A: Inspect its contents. If it contains valid data that was simply misnamed, you may be able to use ALTER TABLE ATTACH PART after renaming it correctly. Otherwise, remove it with ALTER TABLE DROP DETACHED PART.