Troubleshooting

Common failure modes and what to do next.

All models blocked / failed

  • Run /setup and confirm at least one valid key.
  • Run /model and 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=48

Also split the objective into smaller tasks.

Import / install issues

python3 --version   # need 3.9+
pip install -U vritraai
vritraai --help