Umbrel / BTCPay Server / Bitcoin Core 31.0.0 issue — troubleshooting and possible fix via SSH
Problem:
After updating Bitcoin Core / Bitcoin Node to 31.0.0 on Umbrel, BTCPay Server 2.3.9 stays stuck on:
“Your nodes are syncing”
BTC-chain payments are unavailable. BTCPay cannot read the Bitcoin wallet balance or transaction movements from Bitcoin Core / NBXplorer. Withdrawals and Bitcoin payments do not work.
This may be related to NBXplorer compatibility with Bitcoin Core 31.0.0, or to Bitcoin Core 31.0.0 memory/dbcache changes causing problems inside Umbrel containers.
Important:
Do not delete BTCPay Server data, Bitcoin Node data, NBXplorer data, wallet files, or app data unless there is a verified backup and an official recovery procedure.
SSH into Umbrel:
ssh umbrel@umbrel.local
If that does not work, use the Umbrel device IP address:
ssh umbrel@YOUR_UMBREL_IP
Then run the following checks.
- Check running containers:
docker ps --format “table {{.Names}}\t{{.Status}}\t{{.Image}}”
Look for containers related to:
- bitcoin
- bitcoind
- btcpay
- nbxplorer
- Check Bitcoin Core sync status:
docker exec -it bitcoin bitcoin-cli getblockchaininfo
If the container is not called “bitcoin”, find the correct name from docker ps and use it, for example:
docker exec -it bitcoin-cli getblockchaininfo
Check these fields:
“initialblockdownload”: false
“blocks”: should be close to “headers”
If initialblockdownload is true, Bitcoin Core is still syncing.
If blocks and headers are equal or very close and initialblockdownload is false, Bitcoin Core is synced and the problem is likely BTCPay/NBXplorer.
- Check Bitcoin Core wallet/RPC access:
docker exec -it bitcoin bitcoin-cli getnetworkinfo
docker exec -it bitcoin bitcoin-cli getblockcount
docker exec -it bitcoin bitcoin-cli getwalletinfo
If getwalletinfo fails, Bitcoin Core may not have a wallet loaded, or BTCPay may be using NBXplorer instead of Bitcoin Core wallet directly.
- Check BTCPay logs:
docker logs --tail=300 btcpayserver
If the container is not called “btcpayserver”, use the correct name from docker ps:
docker logs --tail=300
Look for errors such as:
- BTC-CHAIN services are not currently available
- Full node not available
- NBXplorer
- RPC error
- settxfee
- paytxfee
- connection refused
- node is syncing
- out of memory
- killed
- Check NBXplorer logs:
docker logs --tail=300 nbxplorer
If the container is not called “nbxplorer”, use the correct name from docker ps:
docker logs --tail=300
Look for errors such as:
- Bitcoin Core RPC error
- unsupported RPC method
- node is not synced
- cannot connect to node
- rescan required
- indexer stuck
- out of memory
- killed
- settxfee
- paytxfee
- Check Bitcoin Core logs:
docker logs --tail=300 bitcoin
Or:
docker logs --tail=300
Look for:
- out of memory
- killed
- dbcache
- RPC errors
- reindex
- corruption
- disk full
- insufficient memory
- Check disk space:
df -h
Also check Docker disk usage:
docker system df
If disk is full or almost full, Bitcoin Core / NBXplorer / BTCPay may fail to sync correctly.
- Check memory pressure:
free -h
Also check running container memory usage:
docker stats
Press CTRL+C to exit docker stats.
If Bitcoin Core, NBXplorer, or BTCPay are using too much RAM, Bitcoin Core 31.0.0 dbcache changes may be causing the issue.
Bitcoin Core 31.0.0 can use a larger default dbcache than previous versions. On smaller Umbrel devices, especially Raspberry Pi or low-RAM systems, try setting dbcache back to a lower value.
Possible workaround:
Add this to bitcoin.conf:
dbcache=450
On Umbrel, the bitcoin.conf location may depend on the version. Common places to check:
ls -la ~/umbrel/app-data/bitcoin/data/bitcoin/
ls -la ~/umbrel/app-data/bitcoin/data/bitcoin/bitcoin.conf
ls -la ~/umbrel/app-data/bitcoin/data/bitcoin/settings.json
If bitcoin.conf exists:
nano ~/umbrel/app-data/bitcoin/data/bitcoin/bitcoin.conf
Add this line:
dbcache=450
Save with:
CTRL+O
ENTER
CTRL+X
Then restart the Bitcoin app/container.
Depending on Umbrel version, use one of these methods:
docker restart bitcoin
Or, if the container has a different name:
docker restart
Then restart BTCPay and NBXplorer:
docker restart nbxplorer
docker restart btcpayserver
Or use the correct container names:
docker restart
docker restart
- After restart, check sync again:
docker exec -it bitcoin bitcoin-cli getblockchaininfo
Then check NBXplorer logs again:
docker logs --tail=300 nbxplorer
Then check BTCPay logs again:
docker logs --tail=300 btcpayserver
- Check NBXplorer version if possible:
docker exec -it nbxplorer nbxplorer --version
If that does not work, try:
docker exec -it nbxplorer dotnet NBXplorer.dll --version
Or inspect the image:
docker inspect nbxplorer | grep -i image
The important thing to confirm:
NBXplorer should be version 2.5.26 or newer for compatibility with the Bitcoin Core 31.0.0 issue reported by BTCPay users.
- Update Umbrel OS and apps from the Umbrel web interface:
Umbrel web UI:
Settings → Software Update
Update umbrelOS if available.
Then update apps:
- Bitcoin Node
- BTCPay Server
- NBXplorer if shown separately
After updates, reboot Umbrel.
- Reboot Umbrel from SSH if needed:
sudo reboot
After reboot, wait for containers to start, then check:
docker ps
docker exec -it bitcoin bitcoin-cli getblockchaininfo
docker logs --tail=300 nbxplorer
docker logs --tail=300 btcpayserver
- If Bitcoin Core is synced but BTCPay still says “Your nodes are syncing”:
This likely means NBXplorer is not synced, not compatible, or cannot communicate correctly with Bitcoin Core 31.0.0.
The likely fix is:
- Umbrel must update the BTCPay Server app package
- Umbrel must include NBXplorer 2.5.26 or newer
- Or Umbrel must provide a supported downgrade/workaround for Bitcoin Core 31.0.0
- Information to send Umbrel support:
Umbrel BTCPay Server 2.3.9 is stuck on “Your nodes are syncing” after Bitcoin Core / Bitcoin Node update to 31.0.0.
BTC-chain payments are unavailable. BTCPay cannot access Bitcoin wallet balance, transaction movements, or withdrawals.
Please confirm:
- Is Umbrel BTCPay Server 2.3.9 compatible with Bitcoin Core 31.0.0?
- Which NBXplorer version is bundled in the Umbrel BTCPay Server package?
- Is NBXplorer version 2.5.26 or newer?
- Is Bitcoin Core 31.0.0 dbcache/memory usage causing container OOM or sync failure?
- Is there an official Umbrel app update, patch, or supported downgrade?
Please do not suggest deleting BTCPay, Bitcoin, NBXplorer, or wallet data unless there is a safe backup and recovery procedure.