ClickHouse DB::Exception: Backup not found

The "DB::Exception: Backup not found" error appears when ClickHouse cannot locate a backup at the path you specified in a RESTORE or incremental BACKUP command. The BACKUP_NOT_FOUND error code means the destination directory or object store prefix either never existed, was deleted, or is unreachable from the current server.

Impact

A BACKUP_NOT_FOUND error blocks the restore operation entirely. No data is recovered, and if you are relying on this backup for disaster recovery or migration, your timeline is directly affected. For incremental backups that reference a missing base, the new backup also cannot proceed.

Common Causes

1. Typo in the backup path or name -- a small spelling difference between what was created and what is referenced in the RESTORE statement.
2. Backup was deleted or expired -- a retention policy or manual cleanup removed the backup files from storage.
3. Wrong storage configuration -- the Disk or S3 configuration in config.xml points to a different bucket, prefix, or mount point than where the backup actually resides.
4. Different ClickHouse node -- in a cluster, the backup was created on one node's local storage and you are trying to restore from another node that does not have access.
5. Permissions issue masquerading as "not found" -- the ClickHouse process lacks read permissions on the backup directory or S3 objects, causing the storage layer to return a not-found response.

Troubleshooting and Resolution Steps

1. Verify the backup name and path. Double-check the exact string you used when the backup was created:

   SELECT name, status, start_time FROM system.backups ORDER BY start_time DESC;
   

2. Confirm the files exist on storage. For local disk:

   ls -la /var/lib/clickhouse/backups/
   

   For S3:

   aws s3 ls s3://my-bucket/clickhouse-backups/
   

3. Check the backup disk configuration. Ensure the disk referenced in your RESTORE statement matches what is defined in your ClickHouse config:

   <storage_configuration>
       <disks>
           <backups>
               <type>local</type>
               <path>/var/lib/clickhouse/backups/</path>
           </backups>
       </disks>
   </storage_configuration>
   

4. Verify file permissions. The clickhouse user must be able to read the backup directory and its contents:

   sudo -u clickhouse ls /var/lib/clickhouse/backups/my_backup/
   

5. For S3 destinations, check IAM permissions. Ensure the ClickHouse instance has s3:GetObject and s3:ListBucket permissions on the backup prefix.

6. If the backup was genuinely lost, restore from an alternative backup or rebuild from replicas if available.

Best Practices

• Maintain an inventory of backups by querying system.backups regularly and storing results externally.
• Use consistent naming conventions across your cluster so backup paths are predictable.
• Set up monitoring or alerts when backup files are deleted, either by retention policies or manual action.
• For shared storage (S3, GCS), ensure all nodes that may need to restore have the correct credentials and endpoint configuration.
• Keep backup metadata alongside the backup files so you can quickly verify what exists.

Frequently Asked Questions

Q: Why does ClickHouse say "not found" when the files are on disk?
A: This usually means the backup disk configuration in ClickHouse does not point to the directory where the files actually reside. Verify the <path> in your disk configuration matches the physical location.

Q: Can I restore a backup created on a different ClickHouse server?
A: Yes, as long as the backup files are accessible from the server running the RESTORE command. Copy the backup to a location the target server can reach, configure the appropriate disk, and reference it in the restore statement.

Q: How can I prevent accidental deletion of backups?
A: Use object lock or versioning on S3, or set restrictive file permissions on local disk. Additionally, always confirm your retention policy window exceeds your longest expected recovery scenario.

Q: Does the BACKUP_NOT_FOUND error apply to incremental backups too?
A: Yes. If you reference a base backup in an incremental backup command and that base does not exist, ClickHouse raises this error (or the related NO_BASE_BACKUP error depending on context).