Diagnosing a stuck node — the field guide

Help & Support
1

Diagnosing a stuck node — the field guide

A common pattern in #issues and #support: “my node was running fine, now it isn’t syncing / can’t connect / says X.” This thread documents the checks to run before asking for help, in order, so you (and we) can resolve faster.

Always include OS + INTcoin version with any help request. uname -a (Linux/macOS) or winver (Windows) + intcoin-cli getnetworkinfo | grep -E "subversion|protocolversion". Most diagnostic time is wasted re-asking for these basics.

Stage 1 — Is the daemon actually running?

# Linux / macOS
intcoin-cli getblockchaininfo | head -5
# or
ps aux | grep intcoind

# Windows
tasklist | findstr intcoind

Expected output: a blocks: <number> line. If you get error: Could not connect to server 127.0.0.1:2211, the daemon is dead.

Common causes of a dead daemon:

  1. OOM kill during RandomX dataset init (~2 GB needed, light mode ~256 MB). Check dmesg | tail -30 for Killed process intcoind lines.
  2. Disk full. Mainnet datadir ~5–10 GB and growing. df -h on the datadir mount.
  3. Crash on shutdown left a stale lock file. Check ~/.intcoin/.lock — if present without a running daemon, delete it: rm ~/.intcoin/.lock.
  4. Datadir corruption after ungraceful shutdown. Try intcoind -reindex-chainstate to rebuild the UTXO set without re-downloading blocks.

Stage 2 — Is the daemon talking to peers?

intcoin-cli getnetworkinfo | jq '{version, subversion, protocolversion, connections, networks: [.networks[] | select(.reachable) | .name]}'
intcoin-cli getpeerinfo | jq '[.[] | {addr, subver, protover: .version, conntime_ago: ((now - .conntime) | floor)}]'

Expected: ≥ 1 connection, peers’ subver matching your major version (/INTcoin Core:1.0.6.1/ etc.).

If connections: 0:

  1. Outbound blocked. Most home networks let intcoind dial out; corporate / hotel / mobile networks often don’t. Test: nc -zv seed1.international-coin.org 2210 should print succeeded.
  2. DNS seeds unreachable. Daemon falls back to hardcoded seed IPs (US 74.208.48.149, EU 82.165.126.194, UK 51.155.97.192). If even these are unreachable, you have an upstream firewall.
  3. Wrong network selected. A -testnet flag on a mainnet datadir won’t find peers. Check getblockchaininfo.chain — it should match what you intended.
  4. Protocol-version mismatch. v1.0.6.1 refuses v1.0.6 peers and earlier. If your subver is 1.0.5 and you can only see 1.0.6.1 peers in the wild, you’ll get zero connections. Upgrade.

Stage 3 — Is the chain actually advancing?

intcoin-cli getblockchaininfo | jq '{blocks, headers, time, time_lag_min: ((now - .time) / 60 | floor), verificationprogress}'

blocks == headers and time_lag_min < 10 minutes means you’re caught up. Common pathologies:

  1. headers > blocks significantly. You’ve fetched headers but blocks aren’t downloading. Either no peers have the blocks (unlikely) or your daemon is bandwidth-throttled. Check getnettotals.uploadtarget.
  2. blocks not advancing for ≥ 30 min. Either the network is stalled (rare; check the public dashboard at Grafana) or you’re on a stuck local fork. Try intcoin-cli reconsiderblock <bestblockhash> to reapply validation.
  3. verificationprogress < 1.0 for hours. Initial Block Download (IBD) — normal for a fresh node, takes 30 min – 2 hours depending on disk speed and network.
  4. Time skew. If your system clock is wrong by > 2 hours, your daemon will reject peer headers as “time too far in future” or “time too old” silently. Check date -u against an NTP source. Run sudo systemctl restart systemd-timesyncd (or ntpd / chrony) if drift is real.

Stage 4 — Is the wallet healthy?

intcoin-cli getwalletinfo
intcoin-cli getbalance
intcoin-cli listunspent 0 9999999 | jq 'length'

Common pathologies:

  1. balance: 0 after mining. Coinbase rewards take 100 confirmations to mature. getwalletinfo.immature_balance shows the maturing portion. Wait.
  2. Wallet not found. The daemon’s auto-open path looks at wallets/default/ only. Custom names need intcoin-cli loadwallet "<name>" after daemon start.
  3. Failed to open wallet: error 2 = WalletError::KEY_NOT_FOUND. Wallet’s LevelDB is missing the hdmaster key — usually a partial-init from a crashed createwallet. Move the broken default/ aside, restorewallet from your seed.
  4. Coinbase rewards going to a different address than expected. The miner uses whatever -address= the unit file specifies, NOT the wallet’s “default” address. Check systemctl cat intcoin-miner (Linux) or the miner CLI args you launched with.

Stage 5 — When to ask for help

After the above, if still broken, post in #issues with:

- OS: <output of uname -a or winver>
- Version: <output of intcoind --version>
- Network: <mainnet / testnet / signet / regtest>
- What you ran: <exact command>
- What happened: <full error message OR last 30 lines of debug.log>
- What you expected: <the expected behaviour>
- Already tried: <stages 1-4 results>

Without those fields the diagnostic loop takes 3-5 round trips. With them, it’s usually 1-2.

Common gotchas worth knowing about

  • HiveOS / RaveOS / mining-distro hosts: not officially supported. INTcoin daemon depends on standard distro libc (Ubuntu 22.04+ / Debian 12+ recommended). Running daemon binaries via ld-linux GLIBC wrappers from miner-distro hosts can break LevelDB key resolution in subtle ways.
  • Apple Silicon Macs: build from source via make -C depends QT=1 then cmake -B build --toolchain=depends/aarch64-apple-darwin/toolchain.cmake. We don’t ship pre-built macOS binaries; the dev runner that exists is for QA only.
  • Windows SmartScreen: right-click the downloaded zip → Properties → Unblock before extracting, else SmartScreen tags every binary inside as untrusted.
  • VPN / Tor users: V2 transport is post-quantum encrypted by default; doesn’t matter if your transport is Tor or clearnet, the application-layer crypto is the same. But check g_reachable_nets if you’re doing -onlynet=onion style isolation — it’ll affect peer-discovery defaults.

— INT-devs