Troubleshooting
Common failure modes and what to do next.
All models blocked / failed
- Run
/setupand confirm at least one valid key. - Run
/modeland pick a free option (gemini-flash-latest,openrouter/free, Groq). - Paid OpenRouter without credits will fail - switch to
:free.
Rate limited (429)
OpenRouter free models can throttle. Failover should try other free ids / Groq instead of burning the whole free catalog on one 429. Wait and retry, or switch provider.
Empty replies from free models
Treated as a hard fault so the agent switches instead of looping forever. Pick another model with /model.
“Done” but hollow HTML/CSS/JS
Content quality rejects stub pages. Ask again with explicit structure and real copy, or name the sections you need.
Tool / shell denied
You (or policy) denied the action. Re-run and approve, or change trust / VRITRA_APPROVAL.
Timeouts / iteration cap
export VRITRA_MODEL_TIMEOUT=180
export VRITRA_AGENT_MAX_ITER=48Also split the objective into smaller tasks.
Import / install issues
python3 --version # need 3.9+
pip install -U vritraai
vritraai --help