Troubleshooting

Start with beekeeper diag. It is the primary tool for diagnosing most issues below, and reports:

• Hook latency (p95/p99)
• Sidecar latency
• Catalog freshness
• ETW loss

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 (exit 2 plus deny JSON; see Security). Re-install the hook so it carries the correct contract, then restart the agent session:

go install github.com/home-beekeeper/beekeeper/cmd/beekeeper@v1.2.0
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.

Install posture warned but I expected a block (or vice versa)

Install-posture warns are advisory and fail soft by default: every rule warns rather than blocks, and an unknown answer (a registry timeout) warns too, so a slow or offline check never stops an install (see Configuration). Inspect each package manager's posture next to what Beekeeper enforces at the hook:

beekeeper posture

If you want a definite violation of a rule to block, opt that rule up:

beekeeper posture enforce release-age --block

Even then the unknown / fail-soft path still warns: a registry outage never blocks an install. To silence a posture warn for one package, use beekeeper posture allow <package> (it never downgrades a catalog malware block).

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