Troubleshooting

Common errors people hit when first running an Exfer node, and what to do.

"Address already in use"

ERROR exfer: FATAL: P2P listener failed on 0.0.0.0:9333: Address already in use (os error 98)

Something else is on port 9333. Either:

Another exfer instance is already running. Stop it:
```
sudo systemctl stop exfer
pgrep -af exfer
```
Another program owns the port. Identify it:
```
sudo ss -ltnp | grep 9333
```
Pick a different port for this instance:
```
exfer node --bind 0.0.0.0:19333
```
Note that peers reach you on whatever port you bind. For inbound P2P connections you'll need to map your firewall / NAT to the same port.

ERROR exfer: node_identity.key has insecure permissions (0644). Refusing to start.

The file must be owner-readable only (0600). Either fix it manually:

chmod 0600 ~/.exfer/node_identity.key

Or let exfer repair it on startup:

exfer node --datadir ~/.exfer --repair-perms

The latter is the right choice for filesystems that strip permissions (WSL on a Windows drive, certain NAS mounts).

If get_block_height doesn't move for minutes despite a working network:

Are the peers healthy? Look at the log for peer N: ... lines. The sync manager rotates to a different peer after a timeout if one stalls.
Are you still in IBD? During cold-bootstrap, header sync runs first; bodies follow. The tip height only advances once bodies start validating.
Check disk space. A full disk silently breaks RocksDB writes.
```
df -h ~/.exfer
```
Restart cleanly. Some peer-state issues clear on restart.

You typed the passphrase wrong, or the file is corrupted. The CLI cannot tell the two apart from outside — both produce a generic decryption failure.

Try a backup copy of the wallet first.
If the backup decrypts, the original file is corrupted (probably truncated by a bad copy). Replace with the backup.
If no backup decrypts, the passphrase is wrong. There is no recovery path.

You passed an address that isn't 64 hex chars. Check:

echo -n "$ADDRESS" | wc -c    # must print 64

exfer wallet send reports balance is too low to cover amount + fee.

Check actual balance: exfer wallet balance --wallet ... --rpc ...
Check amount: did you mean exfers or EXFER? --amount 10 is 10 exfers (0.0000001 EXFER). --amount "10 EXFER" is 10 EXFER. The CLI accepts both forms, but they mean different things.
Mature coinbases only: outputs younger than 360 blocks are excluded.
Dust outputs (below 200 exfers) are skipped.

You hit a rate limit on the RPC endpoint (typically a community node).

For send_raw_transaction: 60 / min / IP.
For UTXO scans (get_balance, get_address_utxos, get_script_utxos): 30 / min / IP.

Back off and retry with jitter. For sustained workloads, run your own node so you control the rate limits.

Demoted from WARN to DEBUG in v1.8.1. If you're on an older binary and the log is dominated by these lines, upgrade to the latest release.

You called send_raw_transaction with bytes that aren't a valid Exfer transaction:

Wrong serialization format (e.g. used Bitcoin's, not Exfer's — see Protocol specification §5).
Hex string has odd length or non-hex characters.
Trailing garbage after the canonical end of the transaction.

Reconstruct with exfer wallet send (which signs correctly), or follow Wallet developer guide for the byte-level construction.

The more reproducible the report, the faster it gets fixed.