Reindex and Recovery

Use the least destructive recovery step that matches the symptom. Most node data can be rebuilt, but wallets must be protected before any recovery action. Stop the node, preserve wallet backups, and copy logs before running heavy rebuilds.

This page covers node data recovery. It is not a replacement for regular backups; see Backups.

Before recovery

Before changing files or starting reindex:

Stop tidecoind.
Back up every wallet with backupwallet if the node can still start.
If the node cannot start, preserve the entire wallets/ directory before touching node data.
Copy recent debug.log files for diagnosis.
Record the exact error message and startup flags.
Check disk free space and filesystem health.

Never delete wallets/ to repair chainstate or block indexes.

Recovery ladder

Step	Command or action	Rebuilds	Keeps local block files?	Use when
Restart cleanly	Start normally after clean shutdown	Nothing	Yes	Process was wedged but storage is healthy.
Rebuild chainstate	`tidecoind -reindex-chainstate`	UTXO set	Yes	Chainstate replay or LevelDB issue on an unpruned node.
Full reindex	`tidecoind -reindex`	Chainstate, block index, active optional indexes	Yes	Block index issue, witness validation warning, or pruned-node recovery path.
Rebuild optional indexes	Disable/delete index data or restart with index flags	Selected indexes	Yes	`txindex`, block filter, or coinstats index is corrupt.
Resync from peers	Move/delete block and chainstate data after wallet backup	Everything	No	Local block files are missing or unusable.

-reindex-chainstate is not compatible with prune mode. Use full -reindex for pruned nodes when the node explicitly requires reindex recovery.

Symptom to action

Symptom or log message	First action
Unable to replay blocks	Try `-reindex-chainstate` on an unpruned node.
Unsupported chainstate database format	Use `-reindex-chainstate` unless the node asks for full reindex.
Witness data after a height requires validation	Use `-reindex`.
Pruned node needs data beyond pruned range	Use `-reindex`; expect redownload if needed.
Prune mode incompatible with `-reindex-chainstate`	Use `-reindex`.
Block index corruption	Use `-reindex`.
Optional index corruption	Rebuild the affected index.
Disk full	Free disk first, then restart or reindex only if errors remain.
Repeated wallet database errors	Stop and protect wallet backups before doing anything else.

If the node gives a specific startup error, follow that error before applying a generic recovery ladder.

What each flag does

Flag	Behavior
`-reindex-chainstate`	Wipes chainstate and rebuilds the UTXO set from existing block files.
`-reindex`	Wipes chainstate and block index, rebuilds them from local `blk*.dat` files, and rebuilds active optional indexes.
`-loadblock=<file>`	Imports blocks from an external block file on startup.

Reindexing does not require deleting wallets. Wallet rescans may happen after node state becomes available, depending on wallet state and available indexes.

Time and disk expectations

Recovery action	Time cost	Disk cost
Restart	Minutes	No extra chain data.
`-reindex-chainstate`	Depends on local block history and disk speed	Needs existing block files and temporary database writes.
`-reindex`	Longer than chainstate rebuild	Rebuilds block index and active indexes.
Resync from peers	Longest	Redownloads block data and rebuilds all local state.

Do not start recovery with a nearly full disk. Rebuilds write new database state and logs, and failures during recovery are harder to diagnose.

Pruned nodes

Pruned nodes intentionally delete old block files. This limits recovery options:

Case	Consequence
`txindex=1` needed	Pruning is incompatible with `txindex`.
`-reindex-chainstate` requested	Prune mode rejects it; use `-reindex`.
Wallet needs blocks older than prune horizon	The node may need full reindex or redownload.
Explorer/indexer workload	Use an unpruned node instead.

If operational recovery speed matters, do not use pruning for exchange, explorer, pool, or indexer nodes.

Safe file handling

When preserving data before recovery, copy or snapshot:

Item	Why
`wallets/`	Protects wallet databases if RPC backup is unavailable.
Wallet backups from `backupwallet`	Preferred recovery artifact.
`tidecoin.conf`	Preserves node role and RPC/network settings.
`debug.log`	Preserves the original failure evidence.
`blocks/`	Can avoid redownloading blocks if usable.

Move questionable node-state directories aside instead of deleting them immediately. For example, with the node stopped, rename chainstate/ to a dated quarantine directory before attempting a rebuild when manual intervention is needed.

Source of truth

Topic	Source
Reindex flags	`../tidecoin/src/init.cpp`
Chainstate recovery errors	`../tidecoin/src/node/chainstate.cpp`, `../tidecoin/src/txdb.cpp`
Data layout	`../tidecoin/doc/files.md`
Wallet backup safety	`../tidecoin/doc/managing-wallets.md`

See also: Backups, Troubleshooting, Data Directory.