ClickHouse DB::Exception: Backup entry not found

The "DB::Exception: Backup entry not found" error means ClickHouse attempted to read a specific file or data entry from within a backup and could not find it. The BACKUP_ENTRY_NOT_FOUND error code indicates that the backup's internal structure is incomplete -- a file listed in the backup metadata is not present in the actual backup data.

Impact

The restore operation fails for the affected table or database. Depending on which entry is missing, you may be able to restore other parts of the backup selectively, but the table referencing the missing entry will not restore. This is a data integrity concern that requires immediate attention.

Common Causes

Incomplete backup write -- the backup process was interrupted before all data parts were written, but the metadata was already finalized.
File deleted from backup storage -- individual files within the backup directory were accidentally removed or lost.
Partial file transfer -- when copying a backup between storage systems, some files were skipped due to transfer errors or timeouts.
Storage-level corruption -- a disk sector failure or S3 object deletion removed specific files within the backup.
Concurrent modification during backup -- in rare cases, data parts being merged or mutated during the backup process can cause references to parts that no longer exist.

Troubleshooting and Resolution Steps

Read the full error message. ClickHouse reports which entry is missing:

DB::Exception: Backup entry not found: data/my_db/my_table/all_3_3_0/data.bin

List the backup contents and compare against metadata:

# List actual files
find /var/lib/clickhouse/backups/my_backup/ -type f | sort > /tmp/actual_files.txt
# Compare with what metadata expects (inspect .backup metadata file)

Check if the missing file exists in another copy of the backup. If you replicated the backup to multiple locations, the file may be intact in one of them:
```
aws s3 ls s3://backup-bucket/my_backup/data/my_db/my_table/all_3_3_0/
```

Try restoring tables individually to isolate which tables are affected:

RESTORE TABLE my_db.table_a FROM Disk('backups', 'my_backup');
RESTORE TABLE my_db.table_b FROM Disk('backups', 'my_backup');

If the backup is unrecoverable, fall back to the most recent intact backup:
```
RESTORE DATABASE my_db FROM Disk('backups', 'previous_good_backup');
```
Re-create the backup from the live data if the source tables still exist:
```
BACKUP DATABASE my_db TO Disk('backups', 'new_backup');
```

Best Practices

Validate backups after creation by performing a test restore or at minimum checking that all expected files are present.
Use storage systems with built-in integrity checks (checksums, object versioning) to detect missing or corrupted files early.
Avoid manual manipulation of files inside backup directories.
When transferring backups between storage systems, use tools that verify transfer completeness (e.g., aws s3 sync with --exact-timestamps).
Configure ClickHouse to freeze parts before backup to minimize the risk of concurrent modifications.

Frequently Asked Questions

Q: Can I restore the backup even with a missing entry?
A: Not for the table that references the missing entry. However, you may be able to restore other tables from the same backup using RESTORE TABLE for each individually.

Q: How do I verify a backup is complete after creating it?
A: Perform a test restore to a temporary database. This is the most reliable validation method. Alternatively, compare the file listing against the backup metadata.

Q: Is BACKUP_ENTRY_NOT_FOUND the same as BACKUP_DAMAGED?
A: They are related but distinct. BACKUP_ENTRY_NOT_FOUND means a specific expected file is absent. BACKUP_DAMAGED is broader and includes checksum mismatches, malformed metadata, and other forms of corruption.

Q: Could this error happen with S3-based backups?
A: Yes. If an S3 object within the backup prefix is deleted or fails to upload, the metadata may reference a file that does not exist in the bucket.