ClickHouse DB::Exception: No base backup found

The "DB::Exception: No base backup found" error occurs when ClickHouse attempts to create or restore an incremental backup but cannot locate the base backup it depends on. The NO_BASE_BACKUP error code indicates a broken backup chain -- the incremental backup references a parent that has been deleted, moved, or was never created.

Impact

This error halts either the incremental backup creation or the restore process. Without the base backup, ClickHouse cannot reconstruct the full dataset because incremental backups only contain the changes since the base. If the base is permanently lost, every incremental backup in that chain becomes unusable for restoration.

Common Causes

1. Base backup was deleted by a retention policy -- automated cleanup removed the base while incremental backups that depend on it still exist.
2. Base backup path changed -- the storage location or disk configuration was modified after the base was created, making it unreachable under its original path.
3. Incorrect base_backup parameter -- the incremental backup command references a wrong or misspelled base backup name.
4. Base backup on a different node -- in a cluster, the base was created on one server's local storage and the incremental is being run on a different server.
5. Storage failure -- the underlying disk or S3 bucket containing the base backup experienced data loss.

Troubleshooting and Resolution Steps

1. Check the base backup reference. Look at the incremental backup command and confirm the base_backup setting points to the correct name:

   BACKUP DATABASE my_db TO Disk('backups', 'incremental_2024-01-16')
   SETTINGS base_backup = Disk('backups', 'full_2024-01-15')
   

2. List available backups to find the actual base:

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

3. Verify the base backup exists on storage:

   ls -la /var/lib/clickhouse/backups/full_2024-01-15/
   # or for S3
   aws s3 ls s3://my-bucket/clickhouse-backups/full_2024-01-15/
   

4. If the base was deleted, create a new full backup and start a fresh incremental chain:

   BACKUP DATABASE my_db TO Disk('backups', 'full_2024-01-16');
   

5. Restore the base backup from a secondary copy if one exists (e.g., replicated to another region or storage tier), then retry the incremental operation.

6. Adjust your retention policy so base backups are never deleted before all their dependent incrementals expire:

   # Retention example: keep base for 30 days, incrementals for 7 days
   # Ensure base outlives the longest incremental chain
   

Best Practices

• Always ensure retention policies account for backup chain dependencies -- a base backup must outlive all its incrementals.
• Tag or label base backups distinctly from incrementals in your naming convention (e.g., full_ vs incr_ prefixes).
• Store a manifest that records which incremental backups depend on which base, so cleanup scripts can check dependencies.
• Periodically create new full backups to limit the length of incremental chains, reducing the risk of a broken chain.
• Test the full restore path (base + incrementals) regularly, not just individual backup creation.

Frequently Asked Questions

Q: Can I restore an incremental backup without its base?
A: No. An incremental backup only contains the data that changed since the base. Without the base, the full dataset cannot be reconstructed.

Q: How do I know which base backup an incremental depends on?
A: Check the backup metadata file inside the incremental backup directory. It records the base backup path. You can also review the base_backup setting used when the incremental was created.

Q: What happens if I delete a base backup that has dependent incrementals?
A: The incrementals will remain on storage, but any attempt to restore them will fail with the NO_BASE_BACKUP error. The incrementals are effectively orphaned.

Q: Is there a maximum chain length for incremental backups?
A: ClickHouse does not enforce a hard limit, but longer chains increase restore time and the risk of a broken chain. A common practice is to take a new full backup weekly and run incrementals daily.