ClickHouse DB::Exception: Unknown disk (Code: 479)

The "DB::Exception: Unknown disk" error in ClickHouse occurs when a query or table definition references a disk name that is not defined in the server's storage configuration. The UNKNOWN_DISK error code (code 479) is raised when ClickHouse cannot find the specified disk in its <disks> configuration section.

Impact

The operation that references the unknown disk fails. This can prevent table creation, ALTER operations, or data moves that specify the disk. Existing tables using a previously valid disk name will also fail to load if the disk configuration was removed or renamed after a restart.

Common Causes

1. A typo in the disk name in the table's SETTINGS storage_policy or an explicit disk reference
2. The disk was not defined in the ClickHouse configuration (config.xml or a file in config.d/)
3. A configuration file that defines the disk was not loaded, it may have incorrect XML syntax or wrong file permissions
4. The disk was removed from the configuration but tables still reference it
5. A table was restored from a backup that used a different storage configuration
6. The configuration uses <include> directives and the included file is missing or inaccessible

Troubleshooting and Resolution Steps

1. Check which disks are currently configured:

   SELECT name, path, type, free_space, total_space
   FROM system.disks;
   

2. Verify the disk name referenced in the error exists in the output above. If it does not, check the storage configuration files:

   grep -r '<disks>' /etc/clickhouse-server/ --include="*.xml"
   

3. A typical disk configuration looks like this in config.xml or a config.d/ file:

   <storage_configuration>
       <disks>
           <my_disk>
               <path>/mnt/data/clickhouse/</path>
           </my_disk>
       </disks>
   </storage_configuration>
   

4. If the disk was recently added, reload the configuration or restart ClickHouse:

   SYSTEM RELOAD CONFIG;
   

5. Verify that the disk's path exists and is accessible by the ClickHouse user:

   ls -la /mnt/data/clickhouse/
   sudo -u clickhouse test -w /mnt/data/clickhouse/ && echo "writable" || echo "not writable"
   

6. If a table references a removed disk, check which tables use it:

   SELECT database, table, name, disk_name
   FROM system.parts
   WHERE disk_name = 'missing_disk_name';
   

7. To move parts from a missing disk, you may need to re-add the disk configuration temporarily, then move the data:

   ALTER TABLE your_table MOVE PARTITION 'partition_id' TO DISK 'default';
   

Best Practices

• Define all disks in a dedicated configuration file (e.g., config.d/storage.xml) to keep storage configuration organized and easy to audit.
• Never remove a disk from the configuration while tables or parts still reference it.
• Use system.disks and system.parts to audit disk usage before making configuration changes.
• Test configuration changes in a staging environment before applying them to production.
• Document disk names and their physical paths so that all team members use consistent names.

Frequently Asked Questions

Q: Can I rename a disk without downtime?
A: No. Disk names are referenced in table metadata and part information. To rename a disk, you need to add the new disk name, move all parts to the new disk, then remove the old disk definition.

Q: What happens if I remove a disk config while data is still on it?
A: ClickHouse will fail to load tables that reference the removed disk. Parts on that disk become inaccessible. You must restore the disk configuration to recover access to the data.

Q: Does the default disk always exist?
A: Yes. ClickHouse always has a default disk that points to the main data directory (typically /var/lib/clickhouse/). You do not need to define it explicitly.