Troubleshooting

Most miner errors are signature, replay, size, or transport failures from the proxy. This page maps the status codes you will see to their cause and fix. Each status is raised by the proxy or the upload verifier in source.

​

Status code reference

​

401 Unauthorized

A 401 means signature verification or identity resolution failed (src/platform_network/master/app_proxy.py:442-443). The specific message comes from the verifier:

missing <header>

One of X-Hotkey, X-Signature, X-Nonce, or X-Timestamp is absent (src/platform_network/security/miner_auth.py:230-234). Set all four headers (src/platform_network/security/miner_auth.py:159-162).

invalid timestamp

X-Timestamp is not an integer (src/platform_network/security/miner_auth.py:163-166). Send Unix seconds as an integer.

stale signature

The timestamp is more than 300 seconds from server time (src/platform_network/security/miner_auth.py:168-169, src/platform_network/config/settings.py:33). Re-sign with a current timestamp and resend promptly.

invalid signature

The signature does not verify against the canonical message (src/platform_network/security/miner_auth.py:181-182). Re-check the message fields and the body hash; the message is platform-upload-v1:{netuid}:{slug}:{METHOD}:{path}:{hotkey}:{nonce}:{timestamp}:{body_hash} (src/platform_network/security/miner_auth.py:96-111). See Authentication & signing.

unknown hotkey

Your hotkey is not in the metagraph (src/platform_network/security/miner_auth.py:213-215). Register on netuid 100; see Wallet & registration.

blocked uid

Your hotkey resolves to UID 0, which is blocked (src/platform_network/security/miner_auth.py:143,217-218).

metagraph unavailable

The metagraph could not be read while a registered hotkey is required (src/platform_network/security/miner_auth.py:204-205,208-210). Retry once the subnet metagraph is reachable again.

​

409 Conflict (nonce replay)

A 409 means the nonce was already used (src/platform_network/master/app_proxy.py:440-441, src/platform_network/security/miner_auth.py:89-90). Generate a fresh, unique nonce for every request. Nonces are retained for 86,400 seconds (src/platform_network/config/settings.py:34).

​

413 Request entity too large

A 413 means the body exceeded the upload limit (src/platform_network/master/app_proxy.py:427-431). The maximum is 7,500,000 bytes (src/platform_network/config/settings.py:35). Shrink the artifact below the limit.

​

502 Bad gateway (Agent Challenge)

A 502 under /challenges/agent-challenge/... is a safe unavailable state from proxy transport handling, not a challenge rejection (docs/miner/README.md:101-103). Work the checklist (docs/miner/README.md:105-112):

​

403 Forbidden (blocked path)

A 403 means the path targets a private challenge route (src/platform_network/master/app_proxy.py:386-390). The proxy blocks /internal/*, /health, /version, and benchmark-execution paths on challenge routes (src/platform_network/master/app_proxy.py:73-74,90-110). Use only the public submission, status, and leaderboard routes.

​

Next steps