Bitcoin Core sync stuck — how to diagnose IBD

Search results for “bitcoin core sync stuck” usually mean one of three things: normal IBD that looks idle, a resource bottleneck (disk, CPU, RAM cache), or a network/peer problem. Reinstalling Core is almost never step one. Use read-only diagnostics from the commands library, then change one variable at a time.

What IBD actually does

Initial Block Download pulls headers, then blocks, then validates them against consensus rules while building the UTXO set. Progress is not linear. Some eras of the chain are denser; validation can sit on one percentage for a long time even while CPU and disk are busy.

Key fields from getblockchaininfo:

• headers — how far your header chain has reached
• blocks — how many full blocks you have validated
• verificationprogress — estimate toward tip (1.0 = caught up)
• initialblockdownload — true while catching up

$ bitcoin-cli getblockchaininfo
$ bitcoin-cli getconnectioncount
$ bitcoin-cli getnetworkinfo

Decision tree

1. Zero peers

If getconnectioncount is 0, sync cannot advance. Check outbound internet, DNS, firewall egress, and whether Tor proxy settings point at a running Tor daemon. Tor-only setups can take longer to find peers — see Tor and privacy.

2. Headers move, blocks crawl

This is the most common “stuck” look. Headers are cheap; block download + validation is expensive. On SD cards, USB spinning disks, or overloaded VPS volumes, blocks lag for days. Mitigations:

• Move the datadir to NVMe (especially on Raspberry Pi — never IBD on SD)
• Raise dbcache if you have spare RAM (see setup sample conf)
• On VPS, check CPU steal and disk IOPS limits — VPS comparison

Hardware IO reality check: hardware comparison.

3. Headers and blocks both frozen

Re-check peers and logs. Look for disk-full errors, permission errors, or corruption messages in journalctl -u bitcoind / debug.log. If the filesystem is full, stop cleanly and free or expand space — do not delete random block files. Disk guidance: pruned vs full.

$ df -h ~/.bitcoin
$ journalctl -u bitcoind -n 80 --no-pager
$ free -h
# Optional: watch CPU while validating
$ top -b -n 1 | head -20

4. Progress near 0.99 forever

Late IBD often feels endless. You are validating recent, denser history and catching mempool/tip race. As long as blocks still increments over a few hours and peers remain, wait. “Stuck at 99%” is a classic false alarm.

What not to do

• Do not kill -9 bitcoind as a habit — prefer bitcoin-cli stop
• Do not wipe ~/.bitcoin because a percentage looked static for one evening
• Do not expose RPC to “monitor sync from your phone on the internet”
• Do not trust random “fast sync” torrents or unsigned snapshots unless you fully understand AssumeUTXO trade-offs

Config knobs that actually help

• dbcache= — more RAM for UTXO cache during IBD (leave headroom for the OS)
• Datadir on fast local NVMe — biggest real-world win
• prune= — does not skip downloading history during IBD; it only discards old blocks afterward

Prune misconceptions are common when people think prune will make IBD tiny. It will not. See pruned vs full for the trust/storage model.

After you reach the tip

When verificationprogress is ~1.0 and initialblockdownload is false, switch to the calm maintenance rhythm: node maintenance checklist. Keep using commands for weekly pulses instead of staring at percentages.

If you are still choosing hardware because sync is unbearable on current gear, compare N100 vs Pi vs used SFF on the hardware page before buying another gadget.

Reading verificationprogress without obsessing

Operators refresh getblockchaininfo every few minutes and conclude the node is dead when the float barely moves. Validation work is bursty. A better habit: note blocks now, walk away for two to four hours, then compare. If blocks increased and peers stayed non-zero, you are not stuck — you are impatient. If blocks is identical after a long wait with peers and free disk, dig into logs and IO.

GUI wrappers can make this worse by showing a single percentage with no headers/blocks split. Prefer bitcoin-cli when diagnosing. The setup guide troubleshooting section mirrors this triage for first-time installs.

VPS-specific stall patterns

Budget clouds sometimes throttle disk or steal CPU when neighbors spike. Symptoms: low verificationprogress change, high system load, and provider metrics showing IO wait. Mitigations: quieter host tier, attached NVMe-class volume, or migrating to hardware you control. Bandwidth caps also matter — IBD can move hundreds of gigabytes once. Review VPS comparison before assuming Core is misconfigured.

FAQ