Skip to content
Minotaur
Open app
+ 01 · Miner

Miner Troubleshooting

Common issues when submitting and iterating on solver code — submission endpoints, screening failures, scoring zeros, and the agent loop.

Common issues when submitting and iterating on solver code. Each section starts with the symptom you’ll see, then walks you through the checks that resolve it.

↳ START · 01 Quickstart Get a miner running end-to-end. ↳ REF · 02 Configuration Full CLI reference. ↳ DEEP · 04 Custom Solver Implementation guidance.

Submission endpoint errors

Error: cannot reach /v1/submissions*

Typical causes:

  • Wrong base URL — using validator :9100 when submissions are served by API :8080 in local testnet
  • API service not running

Checks:

terminal SH 
curl http://localhost:8080/health
curl http://localhost:8080/v1/submissions

Epoch auto-detection failure

Error: Failed to fetch epoch from .../v1/status

submit auto-detects epoch via GET /v1/status. If that endpoint is unavailable on your target, pass --epoch explicitly:

terminal SH 
python -m minotaur_subnet.miner.main submit \
--repo-url <url> \
--commit-hash <hash> \
--hotkey <wallet> \
--epoch 0 \
--validator-url http://localhost:8080 \
--poll

Signature or hotkey issues (git submission)

Error: HTTP 400 / 401 on POST /v1/submissions

Checks:

  • --hotkey points to a real Bittensor wallet name
  • Wallet exists under BT_WALLET_PATH (or default ~/.bittensor/wallets)
  • Commit hash and repo URL match the signed message payload

Screening failures

For git submissions, failures often come from:

  • Missing required files in repo root (Dockerfile, solver.py, README.md)
  • Invalid Dockerfile base image
  • CMD / ENTRYPOINT present in Dockerfile
  • SOLVER_CLASS import / init issues

Local checks:

terminal SH 
docker build --network=none --memory=4g -t test-solver .
docker run --rm --network=none --read-only --tmpfs=/tmp:size=64m \
--memory=2g --cpus=1.0 --entrypoint python test-solver \
-c "from solver import SOLVER_CLASS; print(SOLVER_CLASS.__name__)"

Source submissions not adopted

/v1/submissions/source skips screening and goes straight to benchmarking. If your submission scores but isn’t adopted:

  • Score may be lower than champion
  • Challenger must beat champion by at least 0.5% (DETHRONE_MARGIN = 0.005)

Use the status endpoint to inspect:

terminal SH 
python -m minotaur_subnet.miner.main status \
--submission-id <id> \
--validator-url http://localhost:8080

Score is always zero

Common causes:

  • generate_plan() raises exceptions
  • Malformed ExecutionPlan / calldata
  • Invalid addresses, deadlines, or empty interaction list

Quick check by submitting source and reviewing benchmark / status details:

terminal SH 
curl -X POST http://localhost:8080/v1/submissions/source \
-H "Content-Type: application/json" \
-d '{"solver_source":"<python source>","hotkey":"local-miner","epoch":0}'

Agent loop does not generate submissions

Checks:

  • Claude CLI is installed and available in PATH
  • API URL points to a reachable server exposing /v1/apps/manifests and /v1/submissions/source
  • Strategy directory is writable

Run with explicit options:

terminal SH 
python -m minotaur_subnet.miner.main agent \
--validator-url http://localhost:8080 \
--strategy-dir ./strategies \
--loop-interval 30

Useful commands

terminal SH 
# API health
curl http://localhost:8080/health

# List submissions
curl http://localhost:8080/v1/submissions

# Poll one submission
python -m minotaur_subnet.miner.main status \
--submission-id <id> \
--validator-url http://localhost:8080

See also

↳ START · 01 Quickstart Get a miner running end-to-end. ↳ REF · 02 Configuration Full CLI reference. ↳ DEEP · 04 Custom Solver Implementation guidance and patterns.