Troubleshooting

Common failures and their fixes, grouped by component. Each component also ships a built-in diagnostic — start there:

burrowee doctor              # cli
burrowee gateway doctor      # gateway
burrowee edge doctor         # edge

doctor --fix applies the thin remediations it can (e.g. restarting a down service); --yes skips the prompts.

• Install (all components)
• CLI
• Gateway
• Edge

Install (all components)

Symptom	Cause	Fix
macOS Gatekeeper blocks a downloaded binary	The quarantine attribute on a manually downloaded file (the signed installer flow doesn't hit this)	xattr -d com.apple.quarantine ./burrowee-cli (repeat per binary)
Installer aborts: minisign missing	minisign is the trust root and is never auto-fetched	Install it from your package manager (brew install minisign / apt-get install minisign) and re-run
burrowee <component> → "is not installed on this machine" (exit 127)	The dispatcher found no burrowee-<component> on PATH or in /usr/local/bin, /opt/homebrew/bin, ~/.local/bin	Install that component, or check the bin dir is on PATH — the error lists which components are installed here
Building from source: go build fails with module errors on github.com/burrowee-git/core	It's a private module	Ensure your SSH key has access to burrowee-git and set GOPRIVATE=github.com/burrowee-git/*
Building from source: "no such file or directory ./cmd/burrowee-cli"	You cloned burrowee-git/burrowee (the dispatcher) — the components are separate repos	Clone the component repo (burrowee-git/cli, gateway, edge)

CLI

Symptom	Cause	Fix
bootstrap hangs at "waiting for approval…" then times out	Approval must come from the gateway's local console on the gateway host — not console.burrowee.com	Have the gateway operator check the local console for the pending pairing request and approve it. If it never appeared, the blob's relay URL may point at the wrong relay — ask for a fresh blob
"decrypt blob (wrong PIN?)"	The PIN doesn't match the blob	Ask the gateway operator to confirm the PIN or generate a fresh blob+PIN pair
"gateway public key required (--gw-pub)" / "read gw-pub: …"	The pairing didn't complete or ~/.burrowee/cli/gw.pub is missing	Re-run burrowee bootstrap <blob> <pin> to create it
"daemon: config incomplete"	config.json is absent or was manually edited	Re-run bootstrap to regenerate it
relays list fails with "connect: no such file"	The transport daemon isn't running (relays list is a pure IPC call)	burrowee daemon or burrowee service install. Note relays use <id> still works — it persists to config.json first and only warns about the down daemon
Need to re-pair from scratch	Stale or revoked pairing	rm -rf ~/.burrowee/cli, then bootstrap again with a new blob+PIN from the gateway operator (they can revoke the old pairing in their local console)

Gateway

Symptom	Cause	Fix
Gateway doesn't appear online in console.burrowee.com	The relay URL in the blob isn't reachable from the gateway machine (outbound WSS)	Check ~/.burrowee/gateway/gateway.db exists (bootstrap wrote it), check the service logs for dial errors, and confirm reachability of the relay host — e.g. curl -v https://relay.example.com/ws/gateway
Local console unreachable (http://127.0.0.1:16518)	The daemon started with --console off, or isn't running at all	burrowee gateway service status; restart without --console off. burrowee gateway console prints the URL + a start hint
service install fails on Linux: no systemd	Non-systemd init (OpenRC, runit, …)	Run burrowee-gateway foreground under your own supervisor (ExecStart=burrowee-gateway --no-open equivalent)
bootstrap error: "wrong PIN" / decrypt failure	Blob and PIN must match exactly (case-sensitive blob, digit PIN)	Regenerate from console.burrowee.com → Gateways → Generate setup
Need to re-bootstrap from scratch	Wiping config, relays, and identity	Stop the service first — macOS: launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.burrowee.gateway.plist; Linux: systemctl --user stop burrowee-gateway.service — then rm -rf ~/.burrowee/gateway and bootstrap again (the console issues a new enrollment)

Service logs — macOS: log show --predicate 'process == "burrowee-gateway"' --last 1h (plus ~/.burrowee/gateway/logs/); Linux: journalctl --user -u burrowee-gateway.service -f.

Edge

Symptom	Cause	Fix
"awaiting approval" never flips to active	The operator approved a different edge, or is signed into the wrong account	Confirm the fingerprint shown in the portal matches the one bootstrap printed, and that the approver is the owner-tier account that minted the blob
Console unreachable	The edge only talks to the compiled-in Burrowee console — no override	Check the host's outbound HTTPS/WSS to the console; honor HTTPS_PROXY if behind a proxy
doctor shows custom-domain cert ✗ for a while	DNS propagation + Let's Encrypt issuance take time	Confirm the _acme-challenge CNAME resolves to <slug>.acme.burrowee.net, then re-run doctor after a few minutes
service install fails: systemd not available	Non-systemd init	Run burrowee edge run foreground or under a custom supervisor
status: "enrolled; no config received yet"	The edge hasn't connected while approved	Run burrowee edge run while approved + connected, then re-check
Unhealthy nginx LAN front	Snippet missing, not applied, or nginx down	burrowee edge doctor --fix (install → apply → start), or inspect with burrowee edge nginx --print
Need to re-pair from scratch	Wiping the edge identity	rm -rf ~/.burrowee/edge, then bootstrap again — the console-side pending row must be re-minted

Rotating the LAN cert invalidates pins

burrowee edge nginx --rotate-lan-cert mints a new LAN certificate, so every client/gateway that pinned the old fingerprint must re-paste a fresh blob afterwards. It's a deliberate operator act, not part of routine renewal — the LAN cert is long-lived by design.