Troubleshooting

First stop: run shield360 doctor

It prints the resolved config, the cached session count, the installed plugin paths, and TCP-dials your OTLP endpoint. Exit code 1 means at least one failure; 0 (possibly with warnings) means the CLI is wired up correctly.

No row on the Agents page

The hook never writes to a log file - it emits to stderr, which is captured by the host coding agent’s own logs (Claude Code: ~/.claude/logs/; Cursor: Developer Tools → Console; Codex: ~/.codex/). Set SHIELD360_DEBUG_PAYLOAD_DIR=/tmp/shield360-debug to capture the exact JSON the vendor is sending the hook - useful when fields appear to be missing on the resulting spans.

Hooks ran but no spans landed

Confirm shield360 configure --show reports the right endpoint. The CLI never reads ~/.zshrc; if you set SHIELD360_* in your shell rc, source it before launching the agent.

“Database config not found” on the Agents page

Your Shield360 installation hasn’t run the latest migrations. Restart the shield360 container or run the migration manually (pnpm --filter client run migrate).

---

Setup & Configure

Re-check install, wiring, and endpoint configuration