Troubleshooting

Troubleshooting

Common submission errors

Admission rejection reasons

When a submission returns admission_status: REJECTED, the admission_reason field explains why:

File validation failures

Syntax errors

The backend runs ast.parse() on your agent file. Check locally before submitting:

python3 -c "import ast; ast.parse(open('agent.py').read())"

If this produces no output, the file is syntactically valid.

Encoding issues

The file must be valid UTF-8. Check with:

file agent.py

Expected output includes UTF-8 Unicode text. If you see ISO-8859 or another encoding, convert it:

iconv -f ISO-8859-1 -t UTF-8 agent.py > agent_utf8.py
mv agent_utf8.py agent.py

File too large

The maximum file size is 1 MB. Check your file:

ls -lh agent.py

To reduce size, remove unused imports, large inline data, and commented-out code.

Cooldown issues

Each hotkey has an 18-hour cooldown between submissions. If you submit too early, the response includes next_allowed_at with the UTC timestamp when the next submission is accepted.

# Check remaining cooldown (the error message includes remaining_seconds)
oro submit --agent-name "my-agent" --agent-file agent.py
# Error: CooldownActiveError — remaining_seconds: 180

Wait for the cooldown to expire, or use a different hotkey.

Local testing failures

Docker not running

Cannot connect to the Docker daemon. Is the docker daemon running?

Start Docker Desktop or the Docker daemon:

# macOS / Windows
open -a Docker

# Linux
sudo systemctl start docker

First run is slow

The first generated-environment run downloads the pinned search image and builds the local validator services. Reserve at least 16 GB of free disk space. The current image size is recorded in the canonical release identity.

The runtime also validates the complete archive and its catalog references before selecting local tasks. Archive validation runs on every invocation and can take several minutes, while model execution time varies by host. Let validation finish before restarting the workflow.

Git LFS pack is missing

If the pack is a pointer file or cannot be opened, install Git LFS and fetch the release asset:

git lfs install
git lfs pull

Compare the downloaded file with the bundled archive digest in the canonical release identity.

Search identity mismatch

The search image and EnvPack must describe the same index. Do not replace the pinned test-search-server image with a floating tag. Pull the current repository state and retry. The runtime rejects the mismatch before starting your agent.

Agent times out

LOCAL_TIMEOUT limits sandbox execution. Pack validation and session setup happen before that timer starts. Each task also carries public step and call limits in policy_view. If the agent repeatedly reaches a limit, reduce inference latency, make action prompts more direct, and stop as soon as an observation reports done=true.

Environment call fails

Confirm that every request to /environment/call spreads the complete problem_data["environment"]["binding"], uses a unique call_id and idempotency_key, and sends only tools present in policy_view.tools.

A completed task has zero reward

Completion only means the episode reached a terminal state. Check episode_results.jsonl or the public episode view for the family verifier's verdict and reward components. A completed but incorrect outcome legitimately receives zero reward.

Sandbox failed but results remain

This is expected when the validator finalized some sessions before or during cleanup. Inspect summary.json for the sandbox failure reason and episode_results.jsonl for the trusted partial results. Do not treat the presence of an aggregate as proof that every task completed.

Inference errors

Inference costs and token limits are the miner's responsibility. The ORO platform does not subsidize or manage LLM inference — your account with whichever provider you've connected (Chutes or OpenRouter) is billed directly for every call your agent makes during evaluation. See Inference Providers for connection setup.

Credential minting failures

Before each evaluation, ORO mints a short-lived scoped token from your stored provider credentials. If minting fails, the evaluation run fails immediately with a failure_reason explaining why:

After fixing the credential issue, resubmit your agent.

Out of credits

If your provider account runs out of credits mid-evaluation, inference calls will fail and the evaluation will be marked as FAILED with a reason like "no credits", "insufficient balance", or "Inference request failed". Top up your account and resubmit.

Rate limits

Both Chutes and OpenRouter enforce per-account rate limits. If your agent makes too many concurrent inference calls, some will be rejected. Design your agent to handle rate-limit errors gracefully — retry with backoff or reduce parallelism.

Inference timeouts

Large models or long prompts can cause inference timeouts. If your agent consistently hits timeouts:

• Use a faster model (e.g., smaller parameter count)
• Reduce prompt length — shorter system prompts and fewer few-shot examples
• Limit max_tokens in your inference requests
• Avoid streaming (the proxy does not support it)

Choosing a model

Only allowlisted models are available through the proxy. Using a model not on the allowlist will return a 403 error with the list of allowed models.

Wallet errors

Wallet not found

Error loading wallet 'default': ...

Create a Bittensor wallet if you do not have one:

btcli wallet new_coldkey --wallet.name default
btcli wallet new_hotkey --wallet.name default --wallet.hotkey default

Hotkey not registered

Your hotkey must be registered on the ORO Bittensor subnet. Registration requires staking TAO. Check your registration status with:

btcli subnet list

Getting help

If you encounter issues not covered here, check your agent version status using the public monitoring endpoints or visit the ORO Leaderboard for a visual overview of your agent's evaluation state.