ClickHouse DB::Exception: Wrong base backup

The "DB::Exception: Wrong base backup" error is raised when ClickHouse finds a base backup at the specified location, but its structure or identity does not match what the incremental backup expects. The WRONG_BASE_BACKUP error code means the base backup was likely replaced, modified, or you pointed the incremental at the wrong full backup entirely.

Impact

This error blocks both incremental backup creation and restore operations. Unlike a missing base, the base exists but is the wrong one, which could lead to data inconsistency if ClickHouse did not catch the mismatch. The incremental chain is effectively broken and needs to be rebuilt from a correct base.

Common Causes

Pointing to the wrong base backup -- the base_backup parameter references a different full backup than the one the incremental was originally chained from.
Base backup was overwritten -- the backup at the base path was replaced with a newer full backup, changing its internal UUID or structure.
Schema changes between base and incremental -- tables were altered (columns added, dropped, or type-changed) between the base and the incremental, causing a structural mismatch.
Base backup was partially restored and re-exported -- a reconstructed base may not carry the same internal identifiers as the original.
Copy-paste error in backup scripts -- automated scripts referencing a hardcoded or incorrectly templated base backup path.

Troubleshooting and Resolution Steps

Confirm the base backup identity. Check the metadata inside both the base and incremental backups to verify they are part of the same chain:
```
cat /var/lib/clickhouse/backups/full_2024-01-15/.backup
cat /var/lib/clickhouse/backups/incr_2024-01-16/.backup
```

Verify the base_backup parameter matches the original base:

-- Correct: references the actual base used in the chain
BACKUP DATABASE my_db TO Disk('backups', 'incr_2024-01-17')
SETTINGS base_backup = Disk('backups', 'full_2024-01-15')

Check if the base was overwritten. Compare timestamps and sizes:
```
ls -la /var/lib/clickhouse/backups/full_2024-01-15/
```
If the modification time is newer than expected, the base was likely replaced.
Review schema changes. If the table schema changed between the base and the incremental attempt, the structures will not align:
```
SELECT create_table_query FROM system.tables WHERE database = 'my_db' AND name = 'my_table';
```

Create a new full backup and restart the chain:

BACKUP DATABASE my_db TO Disk('backups', 'full_2024-01-17');
-- Future incrementals reference this new base
BACKUP DATABASE my_db TO Disk('backups', 'incr_2024-01-18')
SETTINGS base_backup = Disk('backups', 'full_2024-01-17')

For restore operations, locate the correct base backup that matches the incremental and use it instead.

Best Practices

Never overwrite a base backup that has dependent incrementals. Use unique names with timestamps for every backup.
Record backup chain relationships in an external manifest or database so you can always identify the correct base.
After schema migrations, take a fresh full backup to start a clean incremental chain.
Use the allow_backup_overwriting setting with caution -- overwriting a base backup orphans all its incrementals.
Validate your backup scripts in a test environment after any changes to naming conventions or storage paths.

Frequently Asked Questions

Q: How does ClickHouse determine if the base backup is "wrong"?
A: ClickHouse stores a unique identifier (UUID) in each backup's metadata. An incremental backup records the UUID of its expected base. If the backup found at the base path has a different UUID, the WRONG_BASE_BACKUP error is raised.

Q: Can I manually fix the base backup reference in an incremental backup?
A: This is not supported or recommended. Editing backup metadata files risks further corruption. The safe approach is to create a new full backup and rebuild the incremental chain.

Q: Does altering a table invalidate existing incremental chains?
A: It can. Significant schema changes (adding or removing columns, changing types) may cause the incremental to be incompatible with the base. Take a new full backup after schema migrations.

Q: What if I have multiple full backups and do not know which one is the correct base?
A: Inspect the metadata file inside the incremental backup -- it records the expected base backup UUID. Compare that UUID against the metadata of your available full backups to find the match.