Node Troubleshooting

Most node incidents fall into a small number of categories: sync and chain state, peer connectivity, disk or database health, RPC access, wallet state, and optional service integrations such as REST or ZMQ. Start with cheap diagnostics before choosing heavy recovery actions.

This page is the diagnostic checklist. It is not the recovery procedure for database rebuilds; see Reindex & Recovery before running -reindex or -reindex-chainstate.

First commands

Run these first:


tidecoin-cli getblockchaininfo
tidecoin-cli getnetworkinfo
tidecoin-cli getmempoolinfo
tidecoin-cli uptime

Then inspect the latest log entries:


tail -n 200 ~/.tidecoin/debug.log

For testnet and regtest, use the matching chain flag and data directory.

Sync is stuck

Check	What to look for
`initialblockdownload`	True means the node still considers itself syncing.
`blocks` vs `headers`	Large persistent gap means block download or validation is lagging.
`verificationprogress`	Should increase during sync.
Peer count	Zero or very low peers points to network connectivity.
Disk free	Low disk can stop block writes or chainstate flushes.
`debug.log`	Validation, blockstorage, coindb, or network errors.

Actions:

Confirm the machine clock is correct.
Confirm peers are connected.
Confirm disk is not full.
Compare best hash and height with another controlled node.
Restart the service if the process is wedged but storage looks healthy.
Use reindex recovery only when logs point to database or block-file issues.

No peers

Check	What to inspect
`getnetworkinfo.networkactive`	Must be true.
`getnetworkinfo.connections`	Total peer count.
Firewall	Outbound P2P must be allowed; inbound is optional but useful.
P2P port	Mainnet `8755`, testnet `18755`, regtest `18778`.
`onlynet`, proxy, Tor/I2P/CJDNS settings	Misconfigured privacy transport can isolate the node.
DNS and seed access	Initial peer discovery depends on usable networking.

Useful debug categories:


debug=net
debug=proxy
debug=tor
debug=i2p

RPC fails

Symptom	Likely cause
`Connection refused`	Node is not running, `server=1` is missing, or RPC is bound elsewhere.
`Unauthorized`	Wrong cookie, `rpcauth`, user, or password.
Timeout	Firewall, overloaded node, or wrong host/port.
Method not found	Wallet disabled, wallet not loaded, or command category unavailable.
Wrong chain data	Client is pointed at the wrong datadir or network.

Check:


tidecoin-cli -getinfo
tidecoin-cli getrpcinfo

Review RPC Security before changing bind or allow rules.

Wallet errors

Symptom	Response
Wallet not loaded	Use `listwallets` and load the intended wallet.
Wallet file locked	Check for another process using the same wallet directory.
Insufficient funds	Check confirmed balance, coinbase maturity, and locked coins.
Address type rejected	Check activation state for post-AuxPoW output types.
Scheme rejected	Check whether the selected PQ scheme is active on that network.
PQHD seed missing	Use `listpqhdseeds` and verify seed defaults.

Do not delete wallet files during node troubleshooting. Wallet backups and node chainstate are separate operational assets.

Disk or database errors

Disk pressure can show up as sync stalls, database write failures, or repeated crashes. Check filesystem free space, OS logs, and debug.log.

If logs mention chainstate database inconsistency or unsupported chainstate format, the node may require -reindex-chainstate or -reindex. Read Reindex & Recovery first because these operations can take significant time.

REST or ZMQ not working

Service	Check
REST	`rest=1`, HTTP bind, firewall, and `debug=http`.
ZMQ	`getzmqnotifications`, publisher address, HWM, subscriber topic, and `debug=zmq`.

REST and ZMQ are not substitutes for RPC-based recovery. If a subscriber missed events, compare its stored tip to getblockchaininfo and backfill by block hash.

Debug category selection

Use narrow debug categories:

Problem	Categories
Peer connectivity	`net`, `proxy`, `tor`, `i2p`
RPC or REST	`rpc`, `http`, `libevent`
ZMQ	`zmq`
Mempool	`mempool`, `mempoolrej`, `txpackages`
Validation	`validation`, `blockstorage`, `coindb`
Reindex	`reindex`, `blockstorage`, `coindb`
Wallet DB	`walletdb`

Disable extra logging after the incident unless it is part of a deliberate monitoring plan.

Source of truth

Topic	Canonical page
Health checks	Monitoring
Recovery actions	Reindex & Recovery
RPC exposure	RPC Security
REST and ZMQ	REST and ZMQ
Activation-dependent wallet behavior	Activation Status

See also: Configuration, Data Directory, Backups.