Troubleshooting

Start with the returned decision and rule ID. Reproduce problems with dummy data, and retain the policy and agent version involved.

Check the installation

Run cyberboar version using the executable path in the agent’s settings.
Run cyberboar check POLICY.
Confirm the hook’s policy, public-key, audit and state paths are accessible to the agent’s account. Managed pull/ship state may belong to a different account from hook tripwire state.
Reload the agent configuration. In Codex, trust user/project hooks in /hooks.
Test allowed and denied calls in a session. If logging is enabled, confirm the matching event.

explain evaluates independently and does not prove a hook is installed. Previewing apply does not write settings; installation requires --write.

Common symptoms

Symptom	Check and recovery
Every call is denied	Check the error reason, policy path/schema, signature, expiry and `minimumVersion`. Development builds meet no version floor.
A denied operation runs	Verify scope, hook loading, Codex trust and audit event. Review agent hook failure and visibility limits.
An ask rule blocks without prompting	Codex, Cursor and opencode receive deny for ask; Copilot also denies in headless mode.
Native Windows calls are blocked	Use Claude Code with Git Bash or another agent with the Linux binary in WSL/a Linux container.
A read gets `builtin.guarded`	Shell access to guarded settings is a potential write. Use a native read tool for inspection; a user must change settings.
A recursive search/archive is blocked	The directory may contain a protected file or built-in protected path. Review `files.containing` and narrow the operation.
`secrets.<id>` blocks test data	Review the finding. Use placeholders; add a justified `secrets.ignore` exception only after review.
Session remains blocked	The tripwire is locked. Inspect with `unlock` and investigate before unlocking.
No audit file exists	Confirm `--audit` in the installed hook. `spec.audit.sink` does not create a log.
Audit errors block calls	Check ownership, append permissions, free space and the absolute path.
Tools break after a binary update/removal	Restore a valid binary at the configured path or update settings with `apply`.

From the affected project directory:

cyberboar explain --policy .cyberboar/policy.yaml --command 'cat .env' --v

For a tripwire, use the hook’s same absolute state directory:

cyberboar unlock --state /absolute/path/to/hook-state
cyberboar unlock --state /absolute/path/to/hook-state --agent claude-code --session SESSION_ID

Signed policy and transport failures

Failure	Action
Invalid/expired signature	Run `verify --pubkey KEY POLICY`. Publish a valid newly signed policy with a higher serial.
Update rejected as rollback	Re-sign older contents with a higher serial; do not delete rollback state to bypass the check.
Pull reports a lock error	Retry after the competing process finishes. The persistent `.lock` filename is normal; the process lock releases on exit.
Redirect or TLS error	Serve directly over TLS 1.3. Use `--ca` for a trusted private CA.
Enrollment refuses another host/name	Follow managed reassignment or migration; enrollment pins console and assignment.
Certificate expired	Re-enroll with a valid token, retaining key and ID. Expired certificates cannot renew.
`401 stale`	Correct endpoint/console clock synchronization.
`ship` cannot deliver	Check enrollment, URL, permissions and signatures. Unacknowledged events remain local for retry.

Enrollment and shipping require a compatible console service. Skip enrollment for local use or static distribution. See Operations, CLI reference and MDM recovery.

Report a problem

For ordinary issues, include OS/architecture, CyberBoar/agent versions, scope, minimal policy, exact tool call and observed rule ID. Remove credentials and unrelated personal data. See Contributing for intake rules.

Send vulnerabilities privately to security@cyberboar.io under SECURITY.md; do not publish bypass details in an issue.