Troubleshooting & Diagnostics

Common node issues, log analysis, benchmark failures, DOS list recovery, and diagnostic techniques.

12 min read

troubleshootingdiagnosticslogserrors

Troubleshooting & Diagnostics

Even well-maintained Flux nodes can encounter issues. This guide covers the most common problems, diagnostic techniques, and solutions. For legacy nodes, the Multitoolbox Option 3 (Analyzer & Fixer) should be your first stop. For ArcaneOS nodes, the SAS protocol handles most issues automatically — but understanding the diagnostics helps when manual intervention is needed.

Common Issues & Solutions

Benchmark Failures

Benchmarks run periodically to verify your node's hardware meets tier requirements. Failures result in the node being removed from the network.

Symptom	Cause	Solution
Benchmark status: "FAILED"	Hardware below tier threshold	Check RAM/SSD/CPU allocation. For VMs, ensure resources are dedicated (not shared).
EPS too low	CPU underperforming	Close competing workloads, check CPU throttling, verify hyperthreading is enabled.
Disk write too slow	SSD performance degradation	Check TRIM support, replace aging SSD, or move to a faster storage backend.
Benchmark stuck/running	FluxBench process hung	Restart FluxBench: Multitoolbox or `sudo systemctl restart zelcash` on legacy.

Node on DOS List

The Denial of Service list contains nodes that failed to confirm or passed failed benchmarks. Check your status:

Check Node Status

# Check DOS list status
curl -s http://YOUR_NODE_IP:16127/daemon/getfluxnodestatus | jq .data.status

•Fix: Ensure daemon is synced, FluxOS is running, and benchmarks pass. The node will automatically rejoin after the next confirmation cycle.
•Quick restart: `sudo systemctl restart zelcash && sleep 120 && sudo systemctl restart flux` (legacy only)

Daemon Out of Sync

•Check sync status: `curl -s http://localhost:16127/daemon/getinfo | jq .data.blocks`
•Compare with network: `curl -s https://api.runonflux.io/daemon/getblockcount | jq .data`
•If far behind: Use Multitoolbox Option 5 (Restore Blockchain) to bootstrap
•If stuck at a specific height: Reindex with Multitoolbox or `flux-cli reindex`

FluxOS API Not Responding

•Check if FluxOS is running: `pm2 list` (should show "flux" as online)
•Check logs: `pm2 logs flux --lines 50`
•Restart FluxOS: `pm2 restart flux`
•If persistent: Reinstall FluxOS via Multitoolbox Option 7
•Check port accessibility: `curl -s http://localhost:16127/flux/version`

Docker Issues

•Docker not running: `sudo systemctl start docker`
•Docker out of disk space: `docker system prune -a` (caution: removes all unused containers and images)
•App containers not starting: Check FluxOS logs for deployment errors
•Network conflicts: `docker network prune` to clean up stale networks

Log Analysis

Key log locations and how to access them:

Log	Access Method	API Endpoint
Daemon log	SSH: ~/.flux/debug.log	GET /flux/daemondebug
Daemon log (tail)	SSH: tail ~/.flux/debug.log	GET /flux/taildaemondebug
Benchmark log	SSH: ~/.fluxbenchmark/debug.log	GET /flux/benchmarkdebug
FluxOS error log	SSH: pm2 logs flux	GET /flux/errorlog
FluxOS info log	SSH: pm2 logs flux	GET /flux/infolog

When seeking help on Discord, always run Multitoolbox Option 3 first and share the output. This gives support volunteers all the diagnostic information they need to help you quickly.

Troubleshooting & Diagnostics