doc: clarify pruning impact on wallet sync #35076

pull MemeticMoney wants to merge 1 commits into bitcoin:master from MemeticMoney:doc-prune-wallet-sync changing 2 files +2 −2

MemeticMoney commented at 7:38 PM on April 14, 2026: none
This updates prune-related help text to document the existing caveat that wallets should remain loaded, and relevant indexes should remain active, while pruning is enabled. This follows the behavior discussed in #30671 without changing startup, pruning, wallet, or index behavior.

Refs #30671.

Testing:
- cmake -S . -B build -DBUILD_GUI=OFF -DBUILD_TESTS=OFF -DBUILD_BENCH=OFF -DBUILD_FUZZ_BINARY=OFF -DENABLE_IPC=OFF -DCMAKE_PREFIX_PATH=/opt/homebrew
- cmake --build build --target bitcoind -j$(sysctl -n hw.ncpu)
- ./build/bin/bitcoind -help 2>&1 | rg -A10 -- '-prune=<n>'
- xmllint --noout src/qt/forms/optionsdialog.ui
- git diff --check
DrahtBot added the label Docs on Apr 14, 2026
DrahtBot commented at 7:39 PM on April 14, 2026: contributor


The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.



Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/35076.



Reviews

See the guideline for information on the review process.

Type Reviewers

Concept ACK GerardoTaboada, willcl-ark

If your review is incorrectly listed, please copy-paste <code></code> into the comment that the bot should ignore.



Conflicts

Reviewers, this pull request conflicts with the following ones:
- #31260 (scripted-diff: Type-safe settings retrieval by ryanofsky)
If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.
MemeticMoney force-pushed on Apr 14, 2026
luke-jr referenced this in commit 8a81c2ce83 on Apr 16, 2026
GerardoTaboada commented at 2:40 AM on April 22, 2026: none

Concept ACK

The added warning accurately describes a real footgun: users who enable pruning while a wallet or index is active can lose access to block data those components still need, requiring a reindex. The change is consistent between the CLI help text (src/init.cpp) and the GUI tooltip (optionsdialog.ui). The wording is clear and actionable.
DrahtBot added the label Needs rebase on Apr 23, 2026
MemeticMoney force-pushed on Apr 25, 2026
MemeticMoney commented at 7:20 PM on April 25, 2026: none

Rebased on current master. No intended content changes beyond resolving the conflict.
DrahtBot removed the label Needs rebase on Apr 25, 2026

Type	Reviewers
Concept ACK	GerardoTaboada, willcl-ark

in src/init.cpp:528 in 584f675abd

 524 | @@ -525,7 +525,7 @@ void SetupServerArgs(ArgsManager& argsman, bool can_listen_ipc)
 525 |                     ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
 526 |      argsman.AddArg("-pid=<file>", strprintf("Specify pid file. Relative paths will be prefixed by a net-specific datadir location. (default: %s)", BITCOIN_PID_FILENAME), ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
 527 |      argsman.AddArg("-prune=<n>", strprintf("Reduce storage requirements by enabling pruning (deleting) of old blocks. This allows the pruneblockchain RPC to be called to delete specific blocks and enables automatic pruning of old blocks if a target size in MiB is provided. This mode is incompatible with -txindex. "
 528 | -            "Warning: Reverting this setting requires re-downloading the entire blockchain. "
 529 | +            "Warning: Reverting this setting requires re-downloading the entire blockchain. Keep any wallets loaded and indexes active while pruning is enabled; if they need old block data that has already been deleted, a reindex may be required. "

willcl-ark commented at 8:35 PM on April 28, 2026:

I think this could actually be made even clearer:

            "Warning: Reverting this setting requires re-downloading the entire blockchain. Wallets and indexes should be loaded at startup and kept active while pruning is enabled so they stay synchronized before old block data is deleted; wallets or indexes that fall behind pruned data may require a reindex.

in src/qt/forms/optionsdialog.ui:58 in 584f675abd outdated

  54 | @@ -55,7 +55,7 @@
  55 |           <item>
  56 |            <widget class="QCheckBox" name="prune">
  57 |             <property name="toolTip">
  58 | -            <string>Enabling pruning significantly reduces the disk space required to store transactions. All blocks are still fully validated. Reverting this setting requires re-downloading the entire blockchain.</string>

willcl-ark commented at 8:36 PM on April 28, 2026:

Similarly here:

            <string>Enabling pruning significantly reduces the disk space required to store transactions. All blocks are still fully validated. Wallets should be loaded at startup and kept active while pruning is enabled so they stay synchronized before old block data is deleted; wallets that fall behind pruned data may require a reindex. Reverting this setting requires re-downloading the entire blockchain.</string>

willcl-ark commented at 8:37 PM on April 28, 2026: member

Concept ACK.

Left two suggestions which IMO clarify this even more.
doc: clarify pruning impact on wallet sync 51ee8ca168
MemeticMoney force-pushed on May 6, 2026
MemeticMoney commented at 8:33 PM on May 6, 2026: none

Thanks, adopted both suggestions.

Contributors

Labels

Linked (view graph)

#30671 bitcoind shouldn't be shutdown automatically despite wallet synchronisation error

doc: clarify pruning impact on wallet sync #35076

Code Coverage & Benchmarks

Reviews

Conflicts