Troubleshooting
Common issues and how to solve them
"No traces found"
Check that the trace directory exists:
ls ~/.watchtower/traces/
Verify the SDK is writing traces:
from watchtower import AgentTracePlugin
# Ensure the plugin is added to your agent
agent = Agent(
plugins=[AgentTracePlugin()]
)"Command not found: watchtower"
Verify the installation:
npm list -g @watchtower/cli
Ensure your PATH includes the npm global bin directory:
# For npm export PATH="$PATH:$(npm config get prefix)/bin" # For pnpm export PATH="$PATH:$(pnpm config get global-bin-dir)"
"Process exited with code 1"
The Python script failed. Check:
- Script path is correct
- Python executable exists
- Script runs successfully standalone:
python my_agent.py
Events not appearing in tail
1. SDK not configured for stdout
Enable stdout streaming in your plugin:
plugin = AgentTracePlugin(
enable_stdout=os.environ.get("WATCHTOWER_LIVE") == "1"
)2. Python buffering output
The CLI sets PYTHONUNBUFFERED=1, but verify your script doesn't override this.
3. Events being filtered
Ensure events have valid type, run_id, and timestamp fields.
Display issues
| Issue | Solution |
|---|---|
| Garbled characters | Ensure terminal supports Unicode |
| Missing colors | Ensure terminal supports ANSI colors |
| Layout broken | Ensure terminal is at least 60 columns wide |