QUANTARA • QUANTUM-RESISTANT L1
Troubleshooting Quantara Devnet-0
Quick checks and common fixes for Quantara Devnet-0 — node startup, sync, RPC, wallet, and performance issues.
Docs • Ops
Troubleshooting guide for Quantara Devnet-0
Start here when something feels off: node won’t start, can’t sync, wallet can’t connect, or performance looks wrong. This page focuses on quick diagnostics and first fixes.
Devnet-0 is intentionally noisy and fast-moving. Not every warning is an incident, but you should have a clear, repeatable way to decide what to do when something looks wrong.
This page gives you a set of quick diagnosis flows for the issues you're most likely to see: node startup failures, sync problems, RPC / wallet errors, and resource bottlenecks. Use it alongside the Incident Response, Rollback & Recovery and Known Issues docs.
The goal is simple: shrink “time-to-first-correct-action” — even if the ultimate root cause ends up being a network-wide incident.
If your checks here suggest a broader issue, stop and escalate via /status and the validator / ops channels instead of debugging in isolation.
Devnet-0 snapshot & quick links
• /status — live incident state & planned maintenance.
• Known issues — bugs and limitations we already know about.
• Launch checklist — canonical setup flow to compare against.
Last updated: 2025-11-23 22:00 UTC. Always cross-check endpoints and incident notes before assuming an issue is local.
1 • First triage
Quick triage: is it you, the network, or the tooling?
Before deep debugging, answer three questions: is the chain healthy, is my node healthy, and is the client / wallet pointing at the right place?
1.1 — Check /status & explorer
- □ Open /status and confirm whether an incident is already active.
- □ Compare head block & finalized height against the explorer.
- □ If both show issues, treat it as a potential network-wide problem.
1.2 — Check another vantage point
- □ Query a reference RPC from another machine / region.
- □ Try a second node or provider if available.
- □ If only one node is misbehaving, treat it as local.
- □ If multiple independent nodes look bad, escalate.
1.3 — Confirm basics
- □ Is DNS resolving your RPC endpoint?
- □ Is your firewall / security group still open as expected?
- □ Did any OS or cloud changes land since last success?
- □ Are you using the correct chain-spec and WS URL?
2 • Node startup
Node won’t start or exits immediately
When the Quantara node fails to start, the logs almost always know why. Here’s how to read them quickly.
2.1 — Immediate checks
- □ Run the node in the foreground once with full logs.
- □ Check for obvious flags errors or unknown options.
- □ Ensure the chain-spec path and name match Devnet-0.
- □ Verify binary version matches what Release Artifacts recommends.
If journald / systemd hides logs, use journalctl -u quantara-node.service -e to see the last lines before exit.
2.2 — Common causes & fixes
- • Port already in use: another node or process is bound to p2p / RPC ports — stop it or change ports.
- • Bad data dir: DB corruption or permission errors — try a fresh data dir, then resync or restore from snapshot.
- • Mismatched spec: delete old chain data and start with the current Devnet-0 spec.
- • Missing libraries: container / OS mismatch — ensure you're on the supported distro or use the recommended Docker image.
3 • Sync issues
Node not syncing, always behind, or stuck
Your node runs but can’t keep up. Decide whether it’s resource-bound, misconfigured, or on the wrong chain.
3.1 — Compare heights
- □ Compare your local height to explorer and reference RPC.
- □ If they match but seem “slow”, it may be a network issue.
- □ If you're far behind, check CPU / disk saturation.
- □ Confirm you're on the expected fork / chain hash.
3.2 — Resource bottlenecks
- □ Check CPU, RAM, disk IOPS, and network metrics.
- □ Look for swap usage or sustained 100% CPU.
- □ Move to NVMe if on slow spinning disks.
- □ Reduce other workloads running on the same host.
3.3 — Peers & connectivity
- □ Confirm you have a healthy peer count.
- □ Check that p2p port is open and reachable.
- □ Use reserved peers / bootnodes from official docs.
- □ If peers look fine but blocks stall, cross-check /status for Sev-1 events.
4 • RPC & wallet
RPC, wallet, or integration issues
Your node is healthy, but clients or wallets can’t talk to it. Most of the time this comes down to URL, CORS, or TLS.
4.1 — Basic RPC health checks
- □ Call basic RPCs: health, system_chain, system_version.
- □ Try both HTTP and WS endpoints if available.
- □ Test from the same machine and from a remote client.
- □ Compare to known-good public RPC if exposed.
See RPC Guide for canonical endpoints and example commands.
4.2 — Wallet & dApp connections
- □ Confirm the wallet is pointed at Devnet-0, not another net.
- □ Verify the WS URL exactly matches your endpoint.
- □ Check browser console for CORS or mixed-content errors.
- □ If using a custom signing extension, confirm permissions.
For faucet and wallet flows, see Wallet & Faucet runbook and Integration guide.
4.3 — TLS, proxies & CORS
- □ Ensure TLS certs are valid and not expired.
- □ Confirm any reverse proxies forward WS upgrade headers.
- □ Check CORS settings match your wallet / dApp origin.
- □ Temporarily bypass proxies to isolate the problem.
5 • Performance
High CPU, RAM, or disk usage
Healthy validators can still run hot. Use these checks to decide when to scale up, tune configs, or escalate.
5.1 — CPU & RAM
- □ Graph CPU and RAM usage over time.
- □ Look for correlation with upgrades or traffic spikes.
- □ Increase vCPUs / RAM if consistently saturated.
- □ Check for runaway loggers or sidecar processes.
5.2 — Disk & I/O
- □ Verify you're on NVMe or equivalent SSD.
- □ Watch for disk saturation or high I/O wait.
- □ Rotate logs and clear old debug dumps.
- □ Plan for DB growth and expand storage proactively.
5.3 — Network
- □ Check latency and packet loss to peers / RPC clients.
- □ Verify your cloud region isn't degraded.
- □ Limit heavy RPC loads on validator nodes; use sentries.
- □ For persistent issues, consider moving regions or ISPs.
6 • Escalation
When & how to escalate to Quantara
Some issues are bigger than any single operator. Here’s how to raise them so we can respond quickly and precisely.
6.1 — Good escalation checklist
- □ You've checked /status and Known Issues.
- □ You've compared against at least one other node.
- □ You have logs, metrics, and timestamps ready.
- □ You can describe severity in Sev-1 / Sev-2 / Sev-3 terms.
6.2 — What to include in your report
- • Node role (validator, RPC, sentry, archive, etc.).
- • Region / provider and approximate start time.
- • Recent changes (upgrades, infra changes, config edits).
- • Short log snippet and key metrics around the event.
Combine this with the Incident Response flow — especially for Sev-1 and Sev-2 events.
Next steps
From troubleshooting to smooth operations
If these flows feel familiar, you’re on your way to mainnet-ready discipline.
Use this page as your first stop when something feels off. If you're here often, consider tightening your Security checklist, Backup & Restore and Localnet guide so you can reproduce and debug issues offline.
Operators who diagnose calmly, escalate clearly, and document what they learn are exactly who we want to grow Quantara's validator set with as we move from Devnet-0 to public testnet and mainnet.