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.