Improve settings.json error message to mention full disk as possible cause #35373

Motivation

When a full disk causes settings.json to be zero-written, Bitcoin Core reports:

"This is probably caused by disk corruption or a crash"

A full disk is a common real-world cause of this exact failure — the file exists but contains zero bytes, producing invalid JSON. The current message does not mention this possibility, leading users to investigate hardware corruption and crashes when the actual cause is simply insufficient disk space.

Possible solution

Change the error message from:

"This is probably caused by disk corruption or a crash"

to:

"This is probably caused by a full disk, disk corruption or a crash"

One-line change in src/util/settings.cpp

Useful Skills

• Compiling Bitcoin Core from source
• Running the C++ unit tests and the Python functional tests
• ...

Guidance for new contributors

Want to work on this issue?

For guidance on contributing, please read CONTRIBUTING.md before opening your pull request.

Hi, I have started working on this as my first issue. Thanks!

glad the hear! here are the full log entries that occurred:

bitcoind | Error: Settings file could not be read: bitcoind | - Settings file /home/bitcoin/.bitcoin/settings.json does not contain valid JSON. This is probably caused by disk corruption or a crash, and can be fixed by removing the file, which will reset settings to default values.

In what way does adding to this error message make it easier to debug the issue? If the disk is full, a ton of other things will fail first, and at least one of those should indicate that the failure is caused by a lack of disk space.

hello @achow101,

Since other messages or clues to the disk being full are not nearby, it doesn't come to mind. The hint directly within this message itself would very much help an operator recognize it as an additional possibility. Is a full disk not also a probable cause?

Can you provide an actual debug.log that demonstrates how this would be more useful?

yes, I'll set it up again, reproduce the scenario and share the debug.log afterwards.

I setup the same scenario by re-installing the host OS Ubuntu 24.04 LTS and left default LV settings which only allocate 100G to /

during IBD, the disk filled. log result this time:

2026-05-28T16:44:49Z UpdateTip: new best=000000000000000002a2e1ddc345b9fe700aa572274cb42e2ebd0a47e7cab403 height=381767 version=0x00000003 log2_work=83.551296 tx=90610866 date='2015-11-02T22:18:41Z' progress=0.066692 cache=1169.5MiB(8771598txo) 2026-05-28T16:44:50Z UpdateTip: new best=00000000000000000ed211b270583c6235f0ecf14611c94a5719ca69dfa81065 height=381768 version=0x00000003 log2_work=83.551323 tx=90612084 date='2015-11-02T22:30:06Z' progress=0.066693 cache=1169.5MiB(8771797txo) 2026-05-28T16:44:50Z UpdateTip: new best=000000000000000005aa0211fe4903d88391654976ae66ff94994769eb739460 height=381769 version=0x00000003 log2_work=83.551350 tx=90614091 date='2015-11-02T22:47:19Z' progress=0.066694 cache=1169.5MiB(8772360txo) 2026-05-28T16:44:50Z [error] Fatal LevelDB error: IO error: /home/bitcoin/.bitcoin/indexes/txindex/001968.log: No space left on device 2026-05-28T16:44:50Z You can use -debug=leveldb to get more complete diagnostic messages 2026-05-28T16:44:50Z [warning]

In my original experience of the failure, the above "No space left on device" error message didn't appear.

I suspect there's a race condition where the "Error: Settings file could not be read" message can sometimes be emitted instead.

In this recent run, the settings file /home/bitcoin/.bitcoin/settings.json is present, but has again been zeroed. I assume it gets zeroed asynchronously and this can result in a race condition as to which error output is emitted.

It would be helpful if the "Error: Settings file could not be read" message could give hint about possibility of a full disk in case it's the one emitted.