Troubleshooting

Start with beekeeper diag: it reports hook latency (p95/p99), sidecar latency, catalog freshness, and ETW loss, and is the primary tool for diagnosing most issues below.

Hook not firing / tool still runs after a block

First confirm the hook is installed and Beekeeper is healthy:

beekeeper diag

If the hook fires but the tool still runs despite a block, the installed hook command is missing the per-harness deny contract. Beekeeper signals a block by exiting 2 plus the deny JSON the harness reads; a hook that exits 1 is treated as a generic error and ignored, so the block is audited but the tool runs. Re-install the hook so it carries the correct contract, then restart the agent session:

go install github.com/home-beekeeper/beekeeper/cmd/beekeeper@latest
beekeeper hooks install --target <harness>

Catalog sync failures

If beekeeper catalogs sync fails, check network connectivity and that the catalog source URLs are reachable. Beekeeper continues in degraded mode from the last-known-good cache; beekeeper diag shows per-source degraded status. To re-fetch and rebuild the mmap index, re-run:

beekeeper catalogs sync

If you installed the background sync daemon, check its state with beekeeper catalogs daemon status. A failing scheduled sync leaves the cache stale until the next successful run, which beekeeper diag will report as reduced catalog freshness.

High latency on beekeeper check

beekeeper check should complete quickly. If beekeeper diag reports high hook latency, re-run beekeeper catalogs sync to rebuild the on-disk index (a stale or fragmented index is the usual cause).

Self-quarantine event

If Beekeeper refuses to run enforcement with a self-quarantine message, the running binary's version matched the beekeeper-self compromise feed. Diagnostic commands remain runnable so you can investigate:

beekeeper version
beekeeper diag
beekeeper selftest
beekeeper policy validate ~/.beekeeper/policies/my-policy.json

Verify the binary (cosign / SLSA; see Installation); if it passes verification but the self-quarantine still fires, the feed entry may be a false positive; file a private advisory.

Policy file rejected

If a policy file is rejected, validate it directly to see the error:

beekeeper policy validate ~/.beekeeper/policies/my-policy.json

The validator rejects unknown fields, exec actions, and unknown rule types.

Nudge not detecting pnpm / bun

Package-manager detection is fail-open by design: it runs pnpm / bun / node --version with a 2-second timeout each, and a slow or missing binary is treated as "not installed" so an advisory never blocks a legitimate install. This timeout is not configurable. Inspect the detected state:

beekeeper nudge status

Note that mode: block enforcement is detection-independent and does not fail open.

Gateway not starting / upstream unreachable

The gateway requires a reachable --upstream MCP server and binds 127.0.0.1 by default. Check status and the bound address:

beekeeper gateway status

Sentry not installed (Linux)

The Sentry daemon is Linux only and is installed via systemd, which requires root:

sudo beekeeper protect install
beekeeper protect status

On non-Linux platforms beekeeper protect prints a "not supported" message. This is expected; the hook and gateway enforcement paths do not depend on the Sentry.

LlamaFirewall sidecar unreachable

Check the sidecar status (PID, uptime, fail mode, degraded flag):

beekeeper llamafirewall status

The prompt-injection scan is a PostToolUse signal and is non-blocking by default; a degraded sidecar does not stop tool calls.

Windows: state directory location

On Windows, Beekeeper's state lives at %APPDATA%\beekeeper\, not ~/.beekeeper/. Config is %APPDATA%\beekeeper\config.json and the audit log is %APPDATA%\beekeeper\audit\beekeeper.ndjson.

Getting help

When filing an issue at github.com/home-beekeeper/beekeeper, include the output of:

beekeeper version
beekeeper diag