#36586 coins: warn of low disk space before chainstate compaction

ReviewabilityReviewsAgreementSize
#36586 l0rinc coins: warn of low disk space before chainstate compactionReady2Disputed28
  • Avoid node crashes and shutdown hangs on low-disk systems by deferring background chainstate compaction
  • Keep compaction status logged by default and skip periodic compaction for in-memory databases
  • Ready to review
  • Support after addressing compaction handling and log phrasing (optout21, stickies-v)
  • Concept approval without stated reasons (sedited)
  • Unaddressed objection: warns on deferred compaction though low-disk users cannot act on it (andrewtoth)
  • Suggests dropping the release note for this change (andrewtoth)
  • 28 lines added or modified outside tests
  • 0 lines added or modified in tests
  • 14 lines removed in total
  • 6 files, 3 commits
Validation#2 of 53
P1 · bug fix
  • P1 because it fixes a stability regression causing node crashes or hung shutdowns on tight disks
  • Compaction temporarily doubles database disk usage, risking disk exhaustion on low-margin nodes
Ranking notes
Reviewability: ReadyStalePaused
Agreement: StrongPositivePositive w/ caveatsNeutralMildDisputedBlockedCrickets
Reviews: current code-review ACKs, then (+stale ACKs) and -NACKs; greener = more ACKs.
Size: lines added or modified outside tests, then in tests; greener = smaller.

Goal

Checks available disk space before starting background chainstate compaction and defers compaction with a warning if free space is less than the assumed chainstate size. Skips periodic compaction entirely for in-memory databases, and moves compaction start and finish logging to the info level by default for both forced and automatic compactions.

Problem: Full LevelDB compaction can temporarily require nearly double the database's disk space before obsolete SST files are removed. On nodes running with tight disk margins, background compaction can exhaust disk space, causing node crashes or hangs on shutdown (as reported in #36585). Furthermore, automatic compaction start and finish messages were hidden under `-debug=coindb`.

Evidence of importance:

  • Linked issue #36585: 'Background chainstate compaction (#35465) filled the disk; node then hung after shutdown (v32.0rc3)'

Risk of a mistake: low (validation). An incorrect disk-space check could defer compaction indefinitely or fail to prevent compaction from running on a full disk.

Changed since the previous assessment: Added a check to skip periodic compaction for in-memory chainstates, and added release notes.

Reviewability

Ready

Nothing known that would invalidate a review now.

Waiting on (from the thread read):

  • author: respond to andrewtoth's pushback on warning when skipping compaction 2026-11-01

Agreement

Disputed

objection that needs a change, the objector pushed back after a reply (andrewtoth)

Thread notes: l0rinc replied to andrewtoth regarding release note wording and defended logging a warning when skipping compaction, but andrewtoth pushed back on the warning objection.

Objections, suggestions, and questions:

ReviewerTypeHarm, request, or questionStatusMust beAuthor repliedQuote
andrewtoth (member)suggestion, approachSkip compaction if there is not enough free disk space rather than only warning and continuingfixed · fix pushed · author pushed an update skipping compaction as suggestedansweredyes2026-10-20: 'Would it make more sense to just skip compaction if we don't think there's enough free disk space to do it?'
Status from: 2026-10-21: l0rinc: 'updated as suggested'
stickies-v (member)question, approachWhether the worst case temporary duplication occurs when a sparse level L-1 causes all files to compact dense level L in one goanswered · author acknowledged investigating partial compactionansweredyes2026-10-21: 'My understanding of the worst case here is that this happens when all the data is on a single level L, with a very sparse (<32MiB) level L-1 above it. Because L-1 is so sparse, all L-1 files (with key'
Status from: 2026-10-22: l0rinc: 'Thanks for the hint, we should investigate that'
stickies-v (member)suggestion, approachCall CompactRange on slices instead of the entire range in one goanswered · author tested compacting smaller ranges and found it could still produce large spikes and is too complex for this PRansweredyes2026-10-21: 'perhaps an alternative approach could be to call `CompactRange` on slices, instead of on the entire (`nullptr`, `nullptr`) range in one go?'
Status from: 2026-10-22: l0rinc: 'I tried compacting smaller key ranges locally, which reduced peak disk usage in some cases but could still produce large'
optout21 (contributor)suggestion, interfaceLog the currently observed available space in addition to the warningfixed · fix pushed · author pushed an update including observed available spaceansweredyes2026-10-22: 'Additionally logging here the currently observed available space is marginally helpful (guideline: if a log is a result of a decision based on several values, log each).'
Status from: 2026-10-23: l0rinc: 'Done, thanks'
optout21 (contributor)suggestion, interfaceAdd explanatory and call-to-action info describing that uncompacted DB takes up more disk space and that the user should free up spacefixed · fix pushed · author pushed an update including recovery guidance in warningansweredyes2026-10-22: 'Could we add some more explanatory and call-to-action info here? Describing that the uncompacted DB takes up more disk space, and that the user should free up some disk space.'
Status from: 2026-10-23: l0rinc: 'Done'
optout21 (contributor)suggestion, interfaceChange wording from 'Skipping' to 'Deferring' to suggest that it is not without consequencesfixed · fix pushed · author updated warning and replied doneansweredyes2026-10-22: 'Also, I suggest changing the wording "Skipping" to "Deferring", to suggest that it's not without consequences.'
Status from: 2026-10-23: l0rinc: 'Done'
stickies-v (member)question, maintenanceWhy CheckDiskSpace() is not being used herefixed · fix pushed · author updated to use CheckDiskSpace() with 50 MiB overheadansweredyes2026-10-23: 'nit: any reason we're not using `CheckDiskSpace()` here?'
Status from: 2026-10-23: l0rinc: 'Guess the extra 50 MiB reserve is fine here (seemed imprecise to me) - changed.'
stickies-v (member)suggestion, approachSkip compaction entirely for in-memory databasesfixed · fix pushed · author updated code to skip automatic in-memory compactionansweredyes2026-10-23: 'For an in-memory database, the compaction memory usage problem is arguably even worse than the on-disk one? Since memory-only is quite ephemeral in nature, I think it's uncontroversial to just skip co'
Status from: 2026-10-23: l0rinc: 'Sure, I was also wondering if someone would comment on bubbling this check up - thanks, done.'
stickies-v (member)suggestion, styleClarify release note phrasing around temporary disk usage during compactionfixed · fix pushed · author clarified release notesansweredyes2026-10-23: 'nit: I found the "may need another database copy" a bit confusing, and think the rest of the phrasing could be a bit more clear as well.'
Status from: 2026-10-23: l0rinc: 'Did something similar, thanks.'
andrewtoth (member)objection, interfaceDo not log a warning when skipping compaction, because running with less than 2x chainstate disk space should be supported and users should not receive warnings for something they cannot act oncontested · author replied that skipping compaction should only be temporary, but andrewtoth pushed back arguing compaction only saves disk space and low-capacity nodes will get unhelpful repeated warningschangedyes2026-10-31: 'I'm not sure we should warn about this. Running on a system with < 2x the chainstate disk space should be supported. If that is the case there is nothing the user can do, and they shouldn't be getting'
Status from: 2026-11-01: andrewtoth: 'Why not? From my understanding the compactions are just a way to reduce disk usage in the chainstate db, but don't affect node operation otherwise.'
andrewtoth (member)suggestion, scopeDo not include a release note for this changeopenansweredno2026-10-31: 'I don't think this change warrants a release note.'
andrewtoth (member)suggestion, styleStrike the phrase 'obsolete data' from the release notes because users will not understand itanswered · author asked whether users need more than understanding garbage collection needs spaceansweredyes2026-10-31: 'at least the last part of this line should be struck."obsolete data" is not something a user reading the release notes will understand.'
Status from: 2026-11-01: l0rinc: 'Do they need to understand more than garbage collection needs a bit more space?'

Support:

  • sedited (member) (Concept ACK, 2026-10-21): (no reason given) [not substantive]
  • stickies-v (member) (Concept ACK, 2026-10-21): (no reason given) [not substantive]
  • optout21 (contributor) (Concept ACK, 2026-10-22): (no reason given) [not substantive]
  • stickies-v (member) (ACK, 2026-10-23): (no reason given) [not substantive]
  • optout21 (contributor) (ACK, 2026-10-24): (no reason given) [not substantive]
  • stickies-v (member) (ACK, 2026-10-26): (no reason given) [not substantive]

Participants:

  • andrewtoth (member, objection, 5 statements 2026-10-20 to 2026-11-01): objected to warning when skipping compaction on low-disk systems and suggested dropping or rewording the release note
  • sedited (member, support, 1 statements 2026-10-21 to 2026-10-21): Concept ACK
  • stickies-v (member, support, 8 statements 2026-10-21 to 2026-10-26): Concept ACK, ACK, re-ACK; asked about LevelDB compaction behavior, suggested compacting by slices, skipping in-memory compaction, and using CheckDiskSpace
  • optout21 (contributor, support, 5 statements 2026-10-22 to 2026-10-24): Concept ACK, ACK; suggested expanding warning message and logging available space

Files

0 lines under test/bench/ci.

  • src/dbwrapper.cpp +9/-8
  • src/validation.cpp +9/-2
  • doc/release-notes-36586.md +6/-0
  • src/dbwrapper.h +2/-2
  • src/txdb.cpp +0/-2
  • src/txdb.h +2/-0

Card

The short text the ranking pass compares across PRs.

Prevents background chainstate compaction from exhausting disk space by checking available filesystem space against the assumed chainstate size before starting, deferring it with a warning if space is insufficient. It also skips compaction for in-memory databases and logs compaction start and finish events at info level by default. In issue #36585 on v32.0rc3, background compaction filled the filesystem and hung the node during shutdown.

Data

dossier JSON · extract JSON · model ledger, generated 2026-11-02T01:11, confidence high, input hash 9fb255253dbf478d
thread read through 2026-11-01 (30 statements), head 2fcfa1dae7
labels: UTXO Db and Indexes

Categories

Validation

P1 · bug fix

Prevents node crashes and shutdown hangs caused by background chainstate compaction exhausting disk space. Issue #36585 reported that automatic background compaction 'filled the disk; node then hung after shutdown (v32.0rc3)', making this an important reliability regression fix for node stability.

Membership: Carries 'UTXO Db and Indexes' label and modifies chainstate compaction in src/validation.cpp, src/txdb.cpp, and src/dbwrapper.cpp.

Factors: security/stability 2, bug 2, performance 0, user value 1, leverage 0