If Bitcoin node is stuck, check the bitcoin "debug.log"

All too often, we see many newcomers here asking for help. I thought it was time for a positive self-help story to encourage others to investigate the bitcoin debug.log for themselves.

Let’s say you find that bitcoin node is not responsive to connections, no indication that it is even syncing is given anywhere whereas it had been working just fine and you can also see several other umbrel apps working just fine. You realize this issue perhaps because Sparrow Wallet or Samurai or some other wallet stopped connecting to your node. Then you look in Umbrel and see Bitcoin node app page is blank. Of course, you will also notice that Lightning Node and BTC explorer don’t work as well since they depend upon the bitcoin node which is now unresponsive to anything. On the other hand, you see that the rest of your umbrel apps not dependent on bitcoin node, like Uptime Kuma are working fine. By the way, I have uptime kuma monitoring btc core port 8333 separately from the other ports used so it too helps let you know where the issue may be since it reports that the btc node is red and unconnected but all my other active umbrel ports are working and responsive. This probably means the hardware is working okay and one doesn’t need to immediately burn a new umbrel sdcard. A more targeted approach to find the issue is needed since one can see it is primarily the bitcoin node itself that stop working.

Now is the time to ssh into your umbrel and dig into the bitcoin data folder by visiting /mnt/data/umbrel/app-data/bitcoin/data/bitcoin and in this folder you should find the debug.log. “tail -n 1000 debug.log” to display the last 1000 lines of the debug.log and you will likely find a repeated error message helping you diagnose the issue. I just encountered a new error that I never had before, namely a " corrupt peers.dat file" causing bitcoin core to not start. The helpful debug.log indicated that if I set the corrupt file aside (copy/cp it to another backup or simply delete it with sudo rm peers.dat) another one would be created at restart. So, with a simple “sudo rm peers.dat” command and then a sudo reboot command. Umbrel restarts and bitcoin node comes back online and starts synching again.

For all newcomers to linux, umbrel, and bitcoin itself, it only takes a little bit of effort to start helping yourselves. Developers have embedded a lot of diagnostic information into all the open source apps we are using because they know better than any of us how easily things can go wrong and how easily they can be fixed if one simply knew where to look. If it is a bitcoin node issue only, here is the place to start:

tail -n 1000 /mnt/data/umbrel/app-data/bitcoin/data/bitcoin/debug.log

Learning to use Bitcoin is necessarily about learning to become more independent. If one wants to use Bitcoin and still expects to depend upon 3rd parties for the use of Bitcoin or an Umbrel Bitcoin node, then one essentially doesn’t really want to use Bitcoin or control one’s own wealth. Effort is required and it is a learning experience. If you want to trust someone else with how to store your wealth, then keep using the banks. If you want to store your wealth yourself, you need to learn how. It isn’t hard with so many developers and educators out there teaching us how, so please don’t ignore the lessons. Independence requires learning. One of the first lessons is simply to distinguish different kinds of wealth: (a) wealth based on physical stuff like gold, (b) wealth based on trust in pieces of paper backed by some authority, and © wealth based on immutable information backed by energy. Each type of wealth requires a different “how to store it” lesson. (a) If it is gold, one needs to trust those who hold it for you or learn how to physically hide and bury it if one is to control it, (b) if it pieces of authoritative paper, then one needs to trust accountants, bankers and financial advisors who know how to legally hide and store it and © if it is information stored electronically in software running on tens of thousands of computers around the world, then one needs to learn a bit about how to keep one’s node running without simply trusting others to fix it for you.


Thanks man!