From a34bfb658e2ee49fb3d1f9b9d162c0ce9fa30035 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=A7=A6=E5=BA=94=E5=8C=96-Surface-pro?= Date: Sat, 4 Apr 2026 16:37:57 -0700 Subject: [PATCH] docs: add troubleshooting section to QUICKSTART.md Added a common issues table and troubleshooting guide to help first-time users resolve frequent problems without opening an issue. --- docs/QUICKSTART.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index b708dc16c..991ef5680 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -398,3 +398,38 @@ curl -sSL https://raw.githubusercontent.com/Scottcjn/Rustchain/main/install-mine *Built by [Elyan Labs](https://elyanlabs.ai) -- $0 VC, a room full of pawn shop hardware, and a belief that old machines still have dignity.* + +--- + +## Troubleshooting + +### Common Issues + +| Problem | Solution | +|---------|----------| +| `Connection refused` when checking balance | The node may be restarting. Wait 30 seconds and retry. | +| `Python not found` | Install Python 3.8+ from [python.org](https://python.org) (macOS/Windows) or `apt install python3` (Linux) | +| `ModuleNotFoundError: requests` | Activate the venv first: `source ~/.rustchain/venv/bin/activate` | +| Miner shows 0 RTC after mining | Mining rewards are paid per epoch (~60 minutes). Check back after an epoch completes. | +| `SSL certificate verify failed` | Your system clock may be wrong. Sync your clock: `sudo ntpdate pool.ntp.org` (Linux) | +| `wallet name already taken` | Wallet names are globally unique. Try a different name with a unique prefix. | + +### Checking Node Status + +If you suspect the network is down, check all attestation nodes: + +```bash +# Check primary node health +curl -sk https://rustchain.org/health + +# Check epoch status +curl -sk https://rustchain.org/epoch + +# If the primary is down, check the backup nodes listed in the README +``` + +### Getting Help + +- **GitHub Issues**: [Open an issue](https://github.com/Scottcjn/Rustchain/issues) +- **Discord**: [Join the community](https://discord.gg/VqVVS2CW9Q) +- **Bounties**: Browse [open bounties](https://github.com/Scottcjn/rustchain-bounties/issues) to earn RTC while learning