#Troubleshooting
| Symptom | Check |
|---|---|
| CLI cannot find the workspace | Run from the directory containing vatio.yml or below it; inspect with vatio doctor |
| CLI authentication fails | Run vatio login; verify the host with vatio doctor |
| Manifest or tool validation fails | Run vatio diff and fix the reported file; unknown root keys and missing instructions are errors |
| A chat was answered by an older version | Run vatio chat show CHAT_ID: its header names the environment and deployment that answered. Compare with vatio status, then vatio publish |
vatio publish is refused with evals_missing, evals_running or evals_regressed | Preview's version is untested, still testing, or breaks a flag live passes: run vatio eval and fix what it lists. See Publishing |
vatio push is refused with preview_has_unpublished_push | Preview holds a version from another branch that is not live yet: publish it first, or push with --force to replace it. See Working with others |
| Agent never calls a tool | Add its key to agent.tools, describe when to use it, push, and start a fresh test chat |
| Knowledge answers are missing | Check vatio kb show BASE, knowledge references, and the knowledge_lookup tool assignment |
| Agent cannot share a URL | Check it is written verbatim in links, in instructions, or in a tool result — an assembled or edited URL is stripped |
| Widget does not appear | Check vatio env (its snippet and token), the token's environment, a deployed agent, and that the host's exact origin is in that token's allowed origins (vatio tokens list, or the tokens section of Channels → Web widget in the inbox) |
| Signed-in visitor appears anonymous | Check auth.public_key matches the key you sign with, and the JWT's signature, exp and aud (the workspace slug) |
Signed-in visitor appears anonymous, with auth: supabase: | The project still signs with the legacy JWT secret (Project Settings → JWT Keys → migrate and rotate), or the app passes a custom storageKey to supabase-js — then call VatioWidget.identify(session.access_token) yourself. See Supabase |
| WhatsApp or Instagram is connected but silent | Run the channel's check; confirm webhook reception and a live agent; WhatsApp must also be activated |
| Agent stopped replying to one chat | Check for human takeover in the inbox and release it when ready |
#Issues
Report bugs and feature requests on the public repository for the piece that misbehaved:
- CLI and platform: github.com/vatio-ai/cli/issues
- Browser SDK: github.com/vatio-ai/sdk/issues
- iOS SDK: github.com/vatio-ai/ios/issues
- Android SDK: github.com/vatio-ai/android/issues
- Ruby gem: github.com/vatio-ai/ruby/issues
Include the failing command, the observed error, a request_id when one is
printed, and the output of vatio doctor. Issues are public: remove
credentials and customer data before you post.