# 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](https://vatio.ai/docs/deployments#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](https://vatio.ai/docs/deployments#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](https://vatio.ai/docs/integrations/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](https://github.com/vatio-ai/cli/issues)
- Browser SDK: [github.com/vatio-ai/sdk/issues](https://github.com/vatio-ai/sdk/issues)
- iOS SDK: [github.com/vatio-ai/ios/issues](https://github.com/vatio-ai/ios/issues)
- Android SDK: [github.com/vatio-ai/android/issues](https://github.com/vatio-ai/android/issues)
- Ruby gem: [github.com/vatio-ai/ruby/issues](https://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.