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 tools check and fix the reported file; unknown root keys and missing instructions are errors
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 widget, the token's environment, a deployed agent, and the host's exact allowed origin
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)
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

Send a bug report or feature request from the CLI:

vatio issue "Describe what happened and what you expected"
vatio issue --template > issue.md
vatio issue --file issue.md
vatio issue list
vatio issue show 42
vatio issue comment 42 "Additional details"
vatio issue "Push is rejected" --no-source

Run from a workspace, vatio issue attaches the directory — the same files vatio push sends. Vatio keeps vatio.yml and everything under tools/, lists the rest by name, and records what its own checks made of them, so a report about a tool arrives with the tool. Any file a check complained about is kept as well. The command prints what it is attaching before it sends; --no-source sends the report alone. Hidden files are never included, so .env and .git/ stay on your machine.

Issue and comment commands send immediately. Review the text before running them. Include the failing command, the observed error, and a request_id when available. The CLI includes its version and workspace context; it does not attach your previous command's output. Remove credentials and customer data from any report. Follow up on the existing thread so the context stays together.