Common Errors
Common errors while running a node and their solutions.
If you experience any issues running your node, here are common errors and their solutions.
Bootstrap and Initialization Errors
| Error | Cause | Solution |
|---|---|---|
failed to connect to bootstrap nodes | • No internet access • NodeID already in use • Old instance still running • Firewall blocking outbound connections | • Check internet connection • Ensure only one node instance is running • Verify firewall allows outbound connections • Confirm staking port (9651) is configured |
subnets not bootstrapped | • Node still syncing with network • Health checks called too early • Network connectivity issues | • Wait for bootstrap to complete (can take hours) • Monitor /api/health endpoint• Ensure stable network connection • Check logs for progress |
db contains invalid genesis hash | • Database from different network • Database corruption • Incompatible database | • Delete database and resync from scratch • Verify correct network connection • Check --network-id flag matches database |
Network and Connectivity Errors
| Error | Cause | Solution |
|---|---|---|
cannot query unfinalized data | • Not connected to other validators • Wrong public IP configured • Port 9651 closed/blocked • Insufficient validator connections | • Configure public IP with --public-ip• Open port 9651 to internet • Allow inbound connections in firewall • Set up port forwarding if behind NAT • Verify peers: curl -X POST --data '{"jsonrpc":"2.0","id":1,"method":"info.peers"}' -H 'content-type:application/json;' http://127.0.0.1:9650/ext/info |
primary network validator has no inbound connections | • Firewall blocking inbound traffic • NAT/router not configured • Wrong public IP advertised • ISP blocking connections | • Configure port forwarding for 9651 • Verify firewall allows inbound • Check public IP: curl ifconfig.me• Test port with online checkers • Use VPS if ISP blocks ports |
not connected to enough stake | • Insufficient validator connections • Network partitioning • Node isolated from network • Bootstrap incomplete | • Check network connectivity • Verify firewall rules • Wait for more connections • Synchronize system time (NTP) |
throttled (Code: -4) | • Too many connection attempts • Rate limiting by peers • Network congestion | • Wait before retrying • Check for connection loops • Reduce connection rate |
Database and Storage Errors
| Error | Cause | Solution |
|---|---|---|
closed | • Database accessed after shutdown • Ungraceful termination • Connection lost | • Restart the node • Check for disk errors or full disk • Verify database files not corrupted |
blockdb: unrecoverable corruption detected | • Ungraceful shutdown (power loss, kill -9) • Disk errors during writes • Hardware failure | • Delete database and resync • Run SMART diagnostics on disk • Ensure 10+ GiB free space • Use UPS for power protection • Maintain regular backups |
| Disk space warnings | • Usage exceeds threshold • Database growth without cleanup • Log accumulation | • Keep at least 10 GiB free (20+ GiB recommended) • Monitor disk usage regularly • Clean up old logs • Set up low-space alerts |
blockdb: invalid block height | • Database corruption • Querying non-existent block • Index corruption | • Verify block height is valid • Resync if corrupted • Check database integrity |
Configuration Errors
| Error | Cause | Solution |
|---|---|---|
invalid TLS key | • TLS key without certificate • Certificate without key • Invalid key format • Corrupted certificate files | • Provide both key and certificate together • Regenerate credentials if corrupted • Verify file permissions • Check certificate format |
minimum validator stake can't be greater than maximum | • Invalid stake configuration • Conflicting parameters • Configuration typos | • Review configuration file • Ensure min < max stake • Check for typos |
uptime requirement must be in the range [0, 1] | • Out-of-range uptime value | • Set uptime requirement between 0 and 1 |
delegation fee must be in the range [0, 1,000,000] | • Invalid delegation fee | • Set fee between 0 and 1,000,000 |
min stake duration must be > 0 | • Invalid stake duration • Min > max duration | • Set min duration > 0 and < max |
sybil protection disabled on public network | • Disabling protection on mainnet/testnet • Security misconfiguration | • Only disable on private networks • Verify network configuration • Remove override for public networks |
plugin dir is not a directory | • Path points to file not directory • Directory doesn't exist • Permission issues | • Create plugin directory • Verify path points to directory • Check read/execute permissions |
Resource and Capacity Errors
| Error | Cause | Solution |
|---|---|---|
insufficient funds | • Insufficient balance for fees • Transaction exceeds balance • Gas estimation too low | • Ensure sufficient balance • Account for transaction fees • Verify balance before submitting |
insufficient gas capacity to build block | • Mempool exceeds block gas limit • Complex transactions • Network congestion | • Wait for congestion to clear • Break into smaller transactions • Increase gas limits if possible |
insufficient history to generate proof | • Partial sync mode • Pruned historical data • Incomplete state sync | • Use full sync for complete history • Wait for state sync to finish • Use archival node for historical data |
Validator and Consensus Errors
| Error | Cause | Solution |
|---|---|---|
not a validator (Code: -3) | • Validator-only operation on non-validator • Stake expired or not active • Not registered as validator | • Verify registration status • Check stake is active • Wait for validation period • Use correct API for node type |
unknown validator | • Not in current validator set • NodeID mismatch • Validator expired/removed | • Verify validator is active • Check end time hasn't passed • Confirm correct NodeID • Query validator set |
Version and Upgrade Errors
| Error | Cause | Solution |
|---|---|---|
unknown network upgrade detected | • Outdated node version • Network upgrade scheduled/active • Incompatible protocol | • Update immediately to latest version • Monitor upgrade announcements • Enable automatic updates • Check version: avalanchego --version |
unknown network upgrade - update as soon as possible | • Network upgrade approaching • Node version outdated | • Update within the day • Check GitHub releases • Plan for maintenance window |
imminent network upgrade - update immediately | • Network upgrade imminent (within hour) | • Critical: Update immediately • Risk of network disconnection |
invalid upgrade configuration | • Upgrade times not chronological • Conflicting schedules • Invalid precompile config | • Review upgrade config files • Ensure sequential timing • Validate precompile settings • Consult upgrade documentation |
API and RPC Errors
| Error | Cause | Solution |
|---|---|---|
Health check: not yet run | • Node still initializing • Bootstrap incomplete • Subnet sync in progress • Network issues | • Wait for initialization • Monitor /api/health for updates• Check individual health checks • Ensure subnets are synced |
timed out (Code: -1) | • Request exceeded timeout • Node overloaded • Network latency | • Increase timeout settings • Check resource usage (CPU/memory/disk) • Reduce request complexity • Use retry with exponential backoff |
| Invalid content-type | • Wrong Content-Type header • Missing header | • Add Content-Type: application/json• Verify API client config • Example: curl -H 'content-type:application/json;' ... |
State Sync Errors
| Error | Cause | Solution |
|---|---|---|
proof obtained an invalid root ID | • State changed during sync • Corrupted merkle proof • Network issues | • Restart state sync • Ensure stable connection • Wait for state to stabilize |
vm does not implement StateSyncableVM interface | • Unsupported VM • Outdated VM version | • Update VM to support state sync • Use full bootstrap instead • Check VM compatibility docs |
Monitoring and Prevention
Key Metrics to Monitor
| Metric | Threshold | How to Check |
|---|---|---|
| Disk Space | Keep 10+ GiB free (20+ GiB recommended) | df -h |
| Network Connectivity | Inbound/outbound connections active | Check firewall, use port scanners |
| Bootstrap Status | Should be bootstrapped | /api/health |
| Validator Connections | Connected to sufficient stake | /ext/info API, check peer count |
| Database Health | No corruption warnings in logs | Monitor ~/.avalanchego/logs/ |
| Node Version | Current with latest release | avalanchego --version |
Best Practices
| Practice | Benefit |
|---|---|
| Use UPS (uninterruptible power supply) | Prevents database corruption from power loss |
| Enable automatic updates | Stay current with security patches |
| Monitor logs regularly | Early detection of issues |
| Keep adequate disk space | Prevent database write failures |
| Configure port forwarding properly | Ensure validator connectivity |
| Synchronize system time with NTP | Prevent consensus issues |
| Backup critical files | Quick recovery from failures |
| Test changes on testnet first | Avoid production issues |
Health Check Endpoints
| Endpoint | Purpose | What It Checks |
|---|---|---|
/ext/health/liveness | Basic process health | Is the node process running? |
/ext/health/readiness | Ready to serve traffic | Is bootstrapping complete? |
/ext/health | Comprehensive status | All health checks and details |
Getting Help
If you encounter errors not listed here:
- Check Logs: Review
~/.avalanchego/logs/for detailed error messages - Search Forum: Avalanche Forum
- Join Discord: Avalanche Discord
- GitHub Issues: Review existing issues
- Provide Context: Include specific error messages, logs, and configuration when asking for help
Quick Diagnostic Commands
# Check node version
avalanchego --version
# Check disk space
df -h
# Check if port 9651 is open
nc -zv <your-public-ip> 9651
# Check node health
curl -X POST --data '{"jsonrpc":"2.0","id":1,"method":"health.health"}' -H 'content-type:application/json;' http://127.0.0.1:9650/ext/health
# Check peers
curl -X POST --data '{"jsonrpc":"2.0","id":1,"method":"info.peers"}' -H 'content-type:application/json;' http://127.0.0.1:9650/ext/info
# Check bootstrap status
curl -X POST --data '{"jsonrpc":"2.0","id":1,"method":"info.isBootstrapped","params":{"chain":"X"}}' -H 'content-type:application/json;' http://127.0.0.1:9650/ext/infoIs this guide helpful?