Skip to main content

🐛 Unit 7 — Debugging & Troubleshooting Lokal

Goal Unit Ini

Di akhir unit ini kamu akan:

  • Punya framework debug yang sistematis: reproduce → read logs → isolate → fix → verify
  • Paham top 10 isu paling umum miner Bittensor lokal dan cara fixnya
  • Bisa baca log btcli dan miner untuk identify masalah
  • Tahu perintah diagnostik per OS untuk network, port, dan process
Prasyarat
  • ✅ Unit 1–6 selesai — miner sudah pernah running (meski ada error)
  • ✅ Familiar dengan terminal dasar

🔧 Framework Debug: 4 Langkah​

Jangan langsung Google atau tanya di Discord kalau ada error. Reproduce dulu, lalu isolate:

📋 Cara Baca Log Miner​

Log miner pakai format: TIMESTAMP | LEVEL | MESSAGE

2026-04-21 10:30:12 | INFO     | Loading wallet mywallet/miner1       ← OK
2026-04-21 10:30:13 | WARNING  | No validators found in metagraph     ← Normal di testnet
2026-04-21 10:30:14 | ERROR    | Connection refused to subtensor      ← MASALAH
2026-04-21 10:30:14 | CRITICAL | Failed to initialize axon            ← FATAL

Lihat Log Berdasarkan Metode Jalankan​

Log langsung tampil di terminal. Scroll up untuk melihat error awal.

Jalankan dengan flag debug untuk log lebih detail:

python neurons/miner.py \
  --netuid 1 \
  --wallet.name mywallet \
  --wallet.hotkey miner1 \
  --subtensor.network test \
  --logging.debug 2>&1 | tee ~/miner.log

Flag 2>&1 | tee ~/miner.log = tampilkan di terminal DAN simpan ke file.

🔟 Top 10 Isu Paling Umum​

Isu 1 — btcli: command not found​

Gejala: Ketik btcli → command not found

Penyebab: venv belum aktif.

# Fix
source ~/bittensor-env/bin/activate
btcli --version  # sekarang harus muncul

Cegah: Tambah alias btenv ke .bashrc / .zprofile (lihat Unit 2).

Isu 2 — ModuleNotFoundError: No module named 'bittensor'​

Gejala: Error import saat python jalan.

Penyebab: venv salah atau bittensor tidak terinstall.

# Verifikasi venv aktif
which python
# Harus: /home/user/bittensor-env/bin/python

# Reinstall SDK
pip install "bittensor<10.0.0"

Isu 3 — ImportError atau AttributeError terkait bittensor​

Gejala: Error seperti cannot import name 'SubnetInfo' from 'bittensor' atau AttributeError: 'subtensor' object has no attribute 'X'

Penyebab: Versi SDK terlalu baru (v10+) tidak kompatibel dengan subnet template.

# Cek versi
python -c "import bittensor; print(bittensor.__version__)"

# Kalau >=10.0.0, downgrade:
pip uninstall bittensor -y
pip install "bittensor<10.0.0"

Isu 4 — Connection refused / Timeout ke Subtensor​

Gejala:

ERROR | SubstrateRequestException: Connection refused
ERROR | Failed to connect to subtensor at test

Penyebab: Subtensor testnet endpoint down atau network issue.

# Coba endpoint alternatif
python neurons/miner.py \
  --netuid 1 \
  --wallet.name mywallet \
  --wallet.hotkey miner1 \
  --subtensor.chain_endpoint wss://test.finney.opentensor.ai:443 \
  --logging.debug

# Atau cek koneksi dasar
curl -s --max-time 5 https://test.finney.opentensor.ai && echo "OK" || echo "FAIL"

Isu 5 — Port 8091 Already in Use​

Gejala:

ERROR | Port 8091 is already in use
OSError: [Errno 98] Address already in use
# Temukan proses yang pakai port
lsof -i :8091

# Kill proses tersebut (ganti <PID> dengan angka dari output lsof)
kill -9 <PID>

# Atau pakai port lain
python neurons/miner.py --axon.port 8092 ...

Isu 6 — Wallet not found / Wallet file corrupted​

Gejala:

ERROR | Wallet not found at path: ~/.bittensor/wallets/mywallet
# Cek wallet tersedia
btcli wallet list

# Cek lokasi file
ls ~/.bittensor/wallets/

# Kalau file ada tapi corrupt, restore dari mnemonic
btcli wallet regen_coldkey --wallet-name mywallet

Isu 7 — Insufficient balance saat Register​

Gejala:

ERROR | Your balance τ 0.0000 is insufficient to pay the registration fee

Solusi:

  1. Minta TAO testnet dari faucet (Unit 3)
  2. Catatan: POW registration dinonaktifkan di NetUID 1, wajib pakai TAO testnet
btcli subnet register \
  --netuid 1 \
  --wallet-name mywallet \
  --hotkey miner1 \
  --network test

Isu 8 — Active: False di Metagraph​

Gejala: Miner jalan tapi btcli subnets metagraph menampilkan Active: False.

Langkah diagnosa:

# 1. Pastikan miner jalan
ps aux | grep miner.py

# 2. Cek port 8091 listening
ss -tlnp | grep 8091       # Linux/WSL2
lsof -i :8091              # macOS/Linux

# 3. Test port dari terminal lain
curl -s http://localhost:8091

# 4. Cek apakah ada firewall block
sudo ufw status            # Linux

Kalau port listening tapi Active: False → kemungkinan CGNAT. Setup Ngrok (Unit 6).

Isu 9 — Miner Exit Tanpa Error Message​

Gejala: Proses langsung mati setelah start, tidak ada error di terminal.

# Jalankan dengan verbose logging, simpan output
python neurons/miner.py \
  --netuid 1 \
  --wallet.name mywallet \
  --wallet.hotkey miner1 \
  --subtensor.network test \
  --logging.debug 2>&1 | tee ~/debug-miner.log

# Baca log
cat ~/debug-miner.log | head -50

Sering penyebabnya: hotkey belum teregister di subnet → cek dengan btcli wallet overview --network test.

Isu 10 — Miner Berjalan tapi Tidak Dapat Reward​

Gejala: Miner Active: True, sudah running berhari-hari, tapi Trust dan emission tetap 0.

Checklist:

# 1. Cek apakah immunity period masih aktif
btcli subnets metagraph --netuid 1 --network test
# Lihat kolom "Immunity"

# 2. Cek apakah ada validator aktif di subnet testnet
# (Testnet mungkin tidak punya validator aktif — normal, tidak ada reward di testnet)

# 3. Cek versi subnet template — harus compatible dengan versi btcli
git -C ~/bittensor-subnet-template log --oneline -5

# 4. Pastikan axon endpoint benar-benar reachable
curl -v http://<public_ip>:8091
Reward Nol di Testnet = Normal

Di testnet, validator mungkin tidak aktif atau emission mekanisme berbeda. GP-0 ini fokus pada belajar flow — bukan actual reward. Reward production ada di mainnet (GP-1/GP-2).

🔍 Diagnostik Lanjutan​

Cek Koneksi Network​

# Ping subtensor
ping -c 4 test.finney.opentensor.ai

# Traceroute ke subtensor
traceroute test.finney.opentensor.ai

# Cek DNS resolve
nslookup test.finney.opentensor.ai

Cek Python Environment​

# Versi Python
python --version

# List semua package di venv
pip list

# Cek spesifik package
pip show bittensor
pip show bittensor-cli

Cek Proses & Resources​

# List proses Python
ps aux | grep python

# Monitor resource real-time
top -p $(pgrep -f miner.py)    # Linux
# htop lebih bagus: sudo apt install htop, lalu: htop

# Cek disk space
df -h ~

🪟 Troubleshooting Khusus Per OS​

ErrorPenyebabSolusi
network unreachable saat start WSL2WSL2 network adapter masalahDi PowerShell: wsl --shutdown, buka Ubuntu lagi
Port tidak bisa diakses dari WindowsPort proxy belum disetnetsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8091 connectaddress=$(wsl hostname -I) connectport=8091 di PowerShell Admin
clock skew error di chainWaktu WSL2 tidak syncsudo hwclock -s atau sudo ntpdate pool.ntp.org
Permission denied saat sudo aptSudo tidak configuredJalankan WSL2, ketik passwd, set password dulu
File path Windows tidak dikenaliPath harus format LinuxGunakan /mnt/c/Users/... bukan C:\Users\...

🆘 Kapan Harus Minta Bantuan​

Setelah coba debug sendiri dan masih stuck, barulah minta bantuan di komunitas. Tips:

  1. Siapkan info lengkap:

    # Copy output ini ke Discord/forum
    python --version
    pip show bittensor | grep Version
    pip show bittensor-cli | grep Version
    uname -a  # atau: sw_vers (macOS)
    btcli --version

  2. Share error message lengkap — bukan screenshot potongan, tapi full stack trace

  3. Coba solusi yang sudah disarankan sebelum tanya lagi (baca thread sebelumnya)

Tempat Tanya​

PlatformChannelUntuk
Discord Bittensor#miner-support, #developer-discussionIssue teknis general
Discord Bittensor#subnet-1-devIssue terkait subnet 1 spesifik
GitHubIssues di opentensor/bittensorBug SDK/btcli
GitHubIssues di repo subnet templateBug template miner

🎯 Rangkuman​

  • Framework debug: reproduce → read logs → isolate → fix → verify
  • Top 3 issue terbanyak: (1) venv tidak aktif, (2) versi SDK salah, (3) port/CGNAT
  • Log lengkap = kunci debugging — selalu pakai --logging.debug
  • Active: False = port tidak reachable → cek firewall atau setup Ngrok
  • Reward nol di testnet = normal — testnet tidak selalu punya validator aktif

✅ Quick Check​

  1. Sebutkan 4 langkah framework debug Bittensor.
  2. Kenapa --logging.debug penting saat debugging?
  3. Apa perbedaan ERROR dan WARNING di log miner?
  4. Bagaimana cara cek proses miner masih jalan di background?
💡 Jawaban
  1. Reproduce → Read Logs → Isolate → Fix → Verify
  2. Tanpa --logging.debug, banyak pesan diagnostic tidak tampil. DEBUG level menampilkan semua detail: koneksi ke validator, query yang masuk, nilai metagraph yang diambil.
  3. WARNING = ada sesuatu yang tidak ideal tapi program masih jalan (misalnya: tidak ada validator aktif). ERROR = ada kegagalan yang perlu ditangani (koneksi gagal, file tidak ditemukan).
  4. ps aux | grep miner.py — kalau ada output dengan path miner.py, proses masih jalan.

🎓 Selesai GP-0!​

Selamat! Kamu sudah menyelesaikan seluruh rangkaian GP-0 Local Mining:

  • ✅ Setup WSL2 / macOS terminal / Linux
  • ✅ Install Python, venv, btcli, Bittensor SDK
  • ✅ Buat wallet coldkey + hotkey, backup mnemonic
  • ✅ Register miner di NetUID 1 testnet (TAO atau POW)
  • ✅ Clone & jalankan subnet-template miner
  • ✅ Setup screen/tmux untuk 24/7 background running
  • ✅ Konfigurasi port dan Ngrok untuk CGNAT
  • ✅ Tahu cara debug isu umum secara sistematis

Kamu sekarang punya fondasi teknis yang kuat untuk lanjut ke production mining:

Debug adalah skill, bukan kelemahan. Miner terbaik adalah miner yang tahu cara fix masalahnya sendiri. 🔧