Bitcoin Core sync stuck: how to diagnose it

Initial block download (IBD) downloads headers first, then the blocks, and checks each one while building the UTXO set. It is bursty, and a slow disk makes it look dead. Four checks separate "working" from "broken".

1. Is it moving?

$ bitcoin-cli getblockchaininfo
{
  "chain": "main",
  "blocks": 612403,
  "headers": 969640,
  "verificationprogress": 0.3944,
  "initialblockdownload": true,
  "size_on_disk": 241837291008,
  "pruned": false,
  "warnings": []
}

(Trimmed output; the numbers are an example.) headers is how far the chain extends, blocks is how many you have verified. A gap with initialblockdownload: true is normal. What matters is whether blocks grows. Note it, wait an hour or two, and run it again. If it grew, you are not stuck. verificationprogress is an estimate by transaction count, so recent blocks move it slowly; do not use it alone.

2. Do you have peers?

$ bitcoin-cli getconnectioncount
10
$ bitcoin-cli getnetworkinfo | grep -E 'networkactive|connections'
  "networkactive": true,
  "connections": 10,
  "connections_in": 0,
  "connections_out": 10,

Zero connections means nothing can advance. Check internet and DNS, networkactive (it is false after setnetworkactive false), firewall egress, and proxy= or onlynet= lines in bitcoin.conf pointing at a Tor daemon that is not running. Tor-only nodes also find peers slowly; see Tor and privacy. Inbound connections only appear if you forward port 8333; outbound is enough to sync.

3. Is the disk or RAM the bottleneck?

Headers race ahead but blocks crawl: the classic slow-hardware pattern. Check:

$ df -h /var/lib/bitcoind
$ free -h
# iostat is in the sysstat package; look at %util and await
$ iostat -x 5 2
$ journalctl -u bitcoind -n 50 --no-pager

• Disk near 100% busy or high await: the disk is the limit. SD cards and USB hard drives are the usual cause; move the datadir to NVMe (hardware). On a VPS, check IOPS and CPU steal in the provider's graphs (VPS).
• Plenty of free RAM: raise dbcache in bitcoin.conf and restart. A bigger UTXO cache means fewer disk writes. Leave room for the OS. See conf reference.
• "Disk space is too low" in the log: go to disk full recovery.
• Permission or corruption errors: stop, fix ownership of the datadir, restart. Rebuild only if Core says the block index is corrupt.

4. Is bitcoind running at all?

$ bitcoin-cli getblockchaininfo
error: timeout on transient error: Could not connect to the server 127.0.0.1:8332

Make sure the bitcoind server is running and that you are connecting to the correct RPC port.
$ systemctl status bitcoind --no-pager

During startup you may see error code: -28 and "Loading block index"; that is the node loading its block index, and it finishes on its own. On slow storage this can take several minutes.

Each of these cases is a scenario in the lab: sync in progress, zero peers, disk full, bitcoind not running. Practice reading the output there first.

Things that do not help

• prune=. It saves disk after verification and does not shorten the download.
• kill -9. Use bitcoin-cli stop; hard kills risk a long recovery on restart.
• Deleting /var/lib/bitcoind because one evening looked static.
• Exposing RPC to watch progress from your phone.

After you reach the tip

When initialblockdownload turns false and blocks equals headers, switch to the maintenance checklist. First install steps and conf are in setup.

FAQ