21Relay
Run Your Node

Stage 7 of 7

Troubleshoot safely

Start with reversible checks. Preserve wallet and configuration data, take notes, and stop before destructive recovery actions you do not understand.

  1. 1Choose setup
  2. 2Check hardware
  3. 3Install
  4. 4Synchronise
  5. 5Maintain
  6. 6Improve privacy
  7. Troubleshoot

Bitcoin Core will not open

  1. 1

    Likely cause

    Another instance, insufficient permissions, missing data drive, security software, an unsupported upgrade path or a startup error in the log.

  2. 2

    Safest first action

    Restart the computer once, confirm the data drive is present, then launch normally without changing files.

  3. 3

    Step-by-step checks

    Check Task Manager or Activity Monitor for an existing process; confirm free space; open debug.log read-only; note the exact final error; compare it with current release notes.

  4. 4

    When not to continue

    Stop if the message mentions wallet corruption, database corruption or an unfamiliar data directory. Back up irreplaceable wallet data before further action.

    Warning: Do not delete wallet files, blocks, chainstate or the whole data directory as an early step.

Initial sync is slow

  1. 1

    Likely cause

    Normal validation load, HDD storage, limited CPU/RAM, antivirus scanning, unstable peers or thermal throttling.

  2. 2

    Safest first action

    Leave the node running on stable power and Ethernet, then compare progress over several hours.

  3. 3

    Step-by-step checks

    Confirm blocks or verificationprogress moves; check SSD activity and temperature; prevent sleep; verify peers; ensure adequate disk space.

  4. 4

    When not to continue

    Pause and investigate if storage disconnects, temperatures are unsafe, errors repeat or progress never changes across a long observation window.

No peer connections

  1. 1

    Likely cause

    Internet outage, disabled network activity, firewall restriction, incorrect proxy/Tor settings, clock error or DNS problems.

  2. 2

    Safest first action

    Confirm ordinary internet access and that networking is enabled in Bitcoin Core.

  3. 3

    Step-by-step checks

    Check system time; review getnetworkinfo; temporarily undo only your most recent network setting; confirm the firewall allows outbound Bitcoin Core traffic.

  4. 4

    When not to continue

    Do not expose RPC or broad inbound ports to fix outbound peers. Inbound port 8333 is optional for basic operation.

Storage is full

  1. 1

    Likely cause

    Archival growth, small pruning target headroom, indexes, logs or unrelated files.

  2. 2

    Safest first action

    Shut the node down normally and free unrelated files on the same volume.

  3. 3

    Step-by-step checks

    Check getblockchaininfo size_on_disk and pruned status; identify large directories without deleting them; consider supported pruning configuration.

  4. 4

    When not to continue

    Stop before manually deleting files inside blocks, chainstate or wallets. Use supported pruning or relocate the complete data directory with verified instructions.

Node appears behind

  1. 1

    Likely cause

    The node was offline, the device slept, peers are unavailable or the local clock is wrong.

  2. 2

    Safest first action

    Keep it open and connected, then check whether the latest block time advances.

  3. 3

    Step-by-step checks

    Compare blocks and headers; check initialblockdownload and warnings; verify peers and system time.

  4. 4

    When not to continue

    Do not trust the node for current wallet confirmation until it reports a recent validated tip.

Database or unclean-shutdown warning

  1. 1

    Likely cause

    Power loss, forced termination, disconnected storage, filesystem trouble or hardware instability.

  2. 2

    Safest first action

    Do not interrupt automatic recovery. Ensure stable power and wait while Core checks its databases.

  3. 3

    Step-by-step checks

    Read the exact warning; check OS disk health and free space; preserve logs; confirm backups of wallet material.

  4. 4

    When not to continue

    Stop before using reindex, reindex-chainstate or deleting databases unless the exact error and official guidance call for it.

Umbrel is unreachable

  1. 1

    Likely cause

    Device is booting, local-name discovery failed, Ethernet is disconnected, IP changed or the OS is unhealthy.

  2. 2

    Safest first action

    Wait five minutes, check power/Ethernet, then try umbrel.local and umbrel. from the same network.

  3. 3

    Step-by-step checks

    Use the router's client list to find the IP; try that IP; connect a display and run hostname -I where the official x86 guide permits.

  4. 4

    When not to continue

    Do not reflash or reinstall while the storage contains unrecovered app or wallet data. Seek official Umbrel support first.

Wallet cannot connect to the node

  1. 1

    Likely cause

    Node not synced, wrong host/port, firewall, wallet-specific server requirement, bad credentials or TLS/VPN mismatch.

  2. 2

    Safest first action

    Confirm the node is synced and reachable locally before changing security settings.

  3. 3

    Step-by-step checks

    Review the wallet's official node-connection method; test from the same machine or LAN; confirm intended service and port; rotate exposed credentials.

  4. 4

    When not to continue

    Never fix this by publishing RPC credentials, disabling all firewall protection or forwarding unrestricted RPC to the internet.

Official sources

Core will not open — official issue trackerSlow initial sync — official P2P guideNo peers — current network RPC helpStorage full — current pruning helpNode behind — blockchain status helpDatabase warning — official issue trackerUmbrel unreachable — official local access stepsWallet connection — official RPC security

Stage progress

Mark this stage complete when you are ready to continue.