Troubleshooting
Fixes for the problems people most often hit setting up the Prismor runtime guard. If you're scanning repos instead, see the CLI docs — that's the separate prismor-cli tool.
Install & setup
| Symptom | Fix |
|---|
PyYAML is not installed (or import yaml fails) | pip3 install pyyaml, then re-run prismor setup. |
prismor: command not found after install | The console script isn't on your PATH. Add $(python3 -m site --user-base)/bin to your shell profile, then open a new terminal. |
pip install prismor succeeds but nothing works | Confirm you didn't install the wrong package — the runtime guard is prismor, not prismor-cli (that's the separate scanner tool). |
| Setup wizard exits immediately in CI | Use prismor setup --non-interactive --mode observe instead of the interactive wizard. |
Enrollment
| Symptom | Fix |
|---|
prismor enroll <token> fails with "token expired" | Enrollment tokens are single-use and expire in 24 hours. Mint a new one from Dashboard → Getting Started checklist → Enroll device. |
| Device enrolled but doesn't show up in the dashboard | Enrollment and hook installation are separate steps — enrolling reports the device to your org, but you still need prismor install-hooks for activity to appear. Give it up to ~30 seconds after enrolling. |
| Enrolled on the wrong org | Run prismor logout and re-enroll with a token minted from the correct org's dashboard. |
Hooks not firing
| Symptom | Fix |
|---|
| Hooks installed but nothing appears in the dashboard | You haven't run an agent session in a hooked workspace yet — the dashboard only shows activity once your agent makes a tool call under policy. |
| Hooks stopped working after an agent update | Re-run prismor install-hooks --agent claude --scope project --mode observe to rewrite the agent's settings file — some agent updates reset local config. |
Installed with --scope project but nothing happens in a different repo | Project scope only applies to the workspace you ran the install command in. Re-run it inside each project you want protected, or use --scope user for a machine-wide default. |
Secret cloaking
| Symptom | Fix |
|---|
| Cloak does nothing | Confirm the agent's tool call references the placeholder syntax @@SECRET:<name>@@, and that the secret is registered: prismor cloak list. |
| Secret still visible in output | Cloaking substitutes real values at execution time and scrubs them from captured output — it doesn't retroactively redact things already printed to your terminal history. |
Still stuck?
- Check
prismor --help and prismor install-hooks --help for the exact flags on your installed version.
- Re-read the Quickstart — most issues are a skipped or reordered step.
- Full setup skill (with more detail than this page):
/docs/agent-setup.