Troubleshooting

Symptom-driven. Find the heading that matches what you're seeing, follow the recipe.

Pages in this section

Symptom	Page	Best for
hivecast status returns nothing useful, browser can't reach the gateway	Host not running	After install, after a reboot, after a crash
Webapp loads but the actor mailbox isn't reachable from the browser	NATS connection failed	Spinner-forever, console shows nats-ws errors
hivecast up <pkg> returns non-zero or runtime stuck in failed	Package failed to start	After installing or upgrading a package
hivecast login --device hangs, errors, or completes but nothing shows up in cloud Devices list	Device pairing failed	After running pairing
EACCES, EPERM, or "you can't write to that directory"	Permission denied	Wrong user owns <host-home> after a reinstall
Need to file an issue or open a support ticket	Collect diagnostics	Captures the right state to share

When all else fails

hivecast doctor --home <host-home> --json

Output is the most concise possible health snapshot. See CLI → exit codes and diagnostics for what each check verifies.

See also

• CLI → exit codes and diagnostics — what an exit code or error message means.
• Local Device → Logs — what to look at when something is silently broken.
• Local Device → Runtime records — for inspecting individual runtime state.

Source: authored from operational experience captured in WORKSTREAMS/launch-readiness-atomic-writes-and-bootstrap/, WORKSTREAMS/product-launch/STATUS.md, and the hivecast doctor checks at projects/matrix-3/packages/hivecast/bin/hivecast.mjs:1031-1187.