CouchDB B-tree Format Recovery After Interrupted Major Version Upgrade

Answer

CouchDB cannot automatically repair a partially migrated B‑tree after an interrupted major version upgrade; manual intervention is required unless a verified pre‑upgrade backup or a healthy replica exists.

Likely explanation

The upgrade script rewrites database headers and B‑tree pages in place without transactional guarantees. If it stops mid‑execution, the on‑disk format may be a hybrid that neither the old nor the new binary can read, leading to startup failures or header version mismatches.

Confirmed facts

Official documentation states that rollback must be performed from a pre‑upgrade backup; there is no documented automatic repair path for hybrid B‑tree states. Errors are observed as unreadable system databases, checksum or version mismatches, and document count discrepancies.

Steps for this case

1. Copy the current data directory to a temporary location.
2. Start the target CouchDB version against the copy in read‑only mode and inspect the log for header, B‑tree, or system‑database load errors.
3. Read the system databases and critical user databases; compare document counts and update sequences with the pre‑upgrade backup or replica.
4. If errors or mismatches are found, restore the verified backup to a clean data directory or rebuild from the healthy replica, then validate startup and replication before switching traffic.
5. Keep the original failed directory unchanged until recovery is confirmed; use it only for diagnostic purposes on the copy.

Missing diagnostic: confirm whether a verified pre‑upgrade backup or a healthy replica is available, as this determines the appropriate recovery path.