ClickHouse DB::Exception: Backup version not supported

The "DB::Exception: Backup version not supported" error occurs when ClickHouse encounters a backup whose internal format version is not recognized by the running server. The BACKUP_VERSION_NOT_SUPPORTED error code typically surfaces when restoring a backup that was created with a significantly newer or older version of ClickHouse than the one performing the restore.

Impact

This error prevents the restore from proceeding. The backup data itself is not damaged, but the current ClickHouse instance cannot interpret its format. This can be a serious obstacle during migrations, rollbacks, or cross-version disaster recovery scenarios where the backup and the target server are on different ClickHouse releases.

Common Causes

1. Restoring a backup from a newer ClickHouse version onto an older one -- backup format changes are typically forward-compatible but not backward-compatible.
2. Major version jump -- skipping several major releases between the version that created the backup and the version attempting the restore.
3. Restoring from a development or pre-release build -- nightly or unstable builds may use format versions not present in stable releases.
4. Mixed-version cluster -- nodes running different ClickHouse versions where one node creates a backup that another node with an older version cannot read.

Troubleshooting and Resolution Steps

1. Identify the backup version. Inspect the backup metadata file (typically .backup or backup_metadata.txt in the backup directory) to find which ClickHouse version created it:

   cat /var/lib/clickhouse/backups/my_backup/.backup
   

2. Check your current ClickHouse version:

   SELECT version();
   

3. Upgrade ClickHouse to match or exceed the backup version. If the backup was created with a newer version, upgrade your target server:

   # Debian/Ubuntu
   sudo apt-get update && sudo apt-get install clickhouse-server clickhouse-client
   

4. If downgrading is required, re-create the backup on a server running the older version. Export the data using clickhouse-client queries and reimport rather than relying on the native backup format:

   -- On the newer server, export data
   SELECT * FROM my_db.my_table INTO OUTFILE '/tmp/my_table.native' FORMAT Native;
   

5. Align cluster versions. Ensure all nodes in a cluster run the same ClickHouse version to avoid format mismatches:

   clickhouse-client --query "SELECT hostName(), version() FROM clusterAllReplicas('my_cluster', system.one)"
   

6. Consult the ClickHouse changelog for your version to understand which backup format versions are supported and whether any breaking changes were introduced.

Best Practices

• Keep all ClickHouse nodes in a cluster on the same version to avoid backup compatibility issues.
• Document the ClickHouse version alongside each backup in your backup inventory.
• Test backup-and-restore workflows after every major ClickHouse upgrade before decommissioning old backups.
• Maintain at least one backup in a portable format (e.g., Native or Parquet exports) for cross-version recovery.
• Follow a rolling upgrade strategy rather than jumping multiple major versions at once.

Frequently Asked Questions

Q: Can I restore a backup from an older ClickHouse version on a newer one?
A: Generally yes. ClickHouse maintains backward compatibility for reading older backup formats. The error typically arises when going in the opposite direction -- restoring a newer backup on an older server.

Q: How do I find which backup format version my backup uses?
A: The backup metadata file inside the backup directory contains format version information. You can also check system.backups on the server that created the backup for version details.

Q: Is there a way to convert a backup to an older format?
A: There is no built-in conversion tool. The recommended approach is to restore the backup on a compatible server and then re-export the data in a portable format that the older server can import.

Q: Will this error corrupt my backup?
A: No. The backup files remain intact. The error simply means the current ClickHouse version cannot interpret the format. Upgrading the server or using a compatible version will allow you to restore successfully.