Bitcoin Core diagnostic commands

Jump to a group

• Sync / IBD health
• Disk / prune
• Peers / network
• Mempool
• Process / logs
• Safe stop / restart

1. Sync / IBD health

Initial Block Download (IBD) can sit at the same percentage for a long time on slow disks. Watch verificationprogress trending toward 1.0, and compare blocks to headers.

$ bitcoin-cli getblockchaininfo

# Useful fields:
# verificationprogress → aim for 1.0
# blocks vs headers → blocks should catch headers
# initialblockdownload → true while catching up
# pruned → true if prune= is enabled

$ bitcoin-cli getconnectioncount

How to read it: If headers advance but blocks stall for hours on NVMe with free disk, check peers and CPU. If both stall, check outbound internet and firewall. Deep dive: sync stuck guide.

2. Disk / prune

A pruned node still downloads the whole chain once during IBD. Free space must cover temporary growth. Never delete random files under ~/.bitcoin/blocks/.

$ df -h ~/.bitcoin

$ bitcoin-cli getblockchaininfo | grep -E 'prune|size_on_disk|verificationprogress'

# OS view of chain data (path may differ on VPS)
$ du -sh ~/.bitcoin/blocks ~/.bitcoin/chainstate 2>/dev/null

How to read it: If the filesystem is >90% full during IBD, stop cleanly and expand disk or enable prune before restart — see disk space & pruned and pruned vs full.

3. Peers / network

Zero peers means no sync. A handful of outbound peers is enough for IBD; inbound peers need port 8333 or Tor.

$ bitcoin-cli getnetworkinfo

$ bitcoin-cli getconnectioncount

# Sample peer rows (can be long — pipe carefully)
$ bitcoin-cli getpeerinfo | head -40

How to read it: Confirm networks show ipv4/ipv6/onion as expected. Tor-only setups often show fewer peers — that can be normal. Privacy notes: Tor and privacy.

4. Mempool (read-only)

Useful after you are near the tip. During early IBD the mempool may be empty or uninteresting.

$ bitcoin-cli getmempoolinfo

# size = tx count; bytes = memory footprint
# mempoolminfee = current minimum relay fee estimate from your node

How to read it: Spikes in mempool size are network congestion, not proof your node is broken. This site does not give fee trading advice.

5. Process / logs

Confirm the daemon is alive before chasing RPC errors. Prefer journald if you use the systemd unit from setup.

$ systemctl status bitcoind --no-pager

$ journalctl -u bitcoind -n 80 --no-pager

# Fallback if not using systemd (do not paste logs publicly — may include paths/IPs)
$ tail -n 50 ~/.bitcoin/debug.log

$ pgrep -a bitcoind

How to read it: Look for disk-full errors, corruption warnings, or repeated connection failures. Do not publish full debug.log dumps — they can leak IPs and paths.

6. Safe stop / restart

Always stop with bitcoin-cli stop (or systemd) so LevelDB flushes cleanly. Hard kills risk a longer restart check.

# Preferred when using systemd (see /setup/)
$ sudo systemctl stop bitcoind
$ sudo systemctl start bitcoind

# Or via CLI if you started bitcoind manually
$ bitcoin-cli stop
$ bitcoind -daemon

$ bitcoin-cli getblockchaininfo

How to read it: After restart, expect a short reindex/verify delay. If the service flaps, check journal logs and disk free space before looping restarts. Maintenance rhythm: node maintenance.

Related pages

• Setup guide — install, conf, systemd
• Sync stuck — IBD not moving
• Disk space & pruned — full disk recovery
• Node maintenance — weekly/monthly checklists
• Security basics — RPC and firewall
• Raspberry Pi 5 node — NVMe-first Pi path

FAQ