Troubleshooting
Find the symptom, follow the fix. If your issue isn’t here, run
hiveloom doctor first — most problems show up there.
DNS
| Symptom | Most likely cause | Fix |
|---|---|---|
dig +short hiveloom.example.com returns nothing | DNS A/AAAA record not set, or not yet propagated. | Add the record at your DNS provider; wait up to TTL (usually a few minutes). See DNS. |
Caddy logs tls: no certificate available | DNS resolves to a different IP than the VPS. | Verify the A record points at the VPS public IP; some providers use proxied/CDN records that hide it. |
TLS / Let’s Encrypt
| Symptom | Cause | Fix |
|---|---|---|
Caddy logs acme: error 429 (rate limited) | Too many cert requests for the same domain in 7 days. | Use --acme-env staging while iterating: hiveloom tls render ... --acme-env staging. See TLS. |
acme: context deadline exceeded | Cloud provider blocks port 80 at the edge (e.g. some VPS firewalls). | Open port 80 on the VPS firewall and the cloud provider’s network firewall. See Firewall. |
acme: HTTP-01 challenge failed | Caddy isn’t reachable on port 80, or DNS is wrong. | curl -I http://hiveloom.example.com/ should return a Caddy banner. |
Reverse proxy
| Symptom | Cause | Fix |
|---|---|---|
OAuth metadata shows http:// URLs over HTTPS | Reverse proxy isn’t forwarding X-Forwarded-Proto. | Use the Caddyfile from hiveloom tls render — it sets the header correctly. |
Browser hangs on https://hiveloom.example.com/ | Caddy not running, or not bound to :443. | sudo systemctl status caddy, sudo ss -tlnp | grep :443. |
| 502 Bad Gateway from Caddy | Hiveloom isn’t running, or it’s bound to a different port than Caddy expects. | hiveloom health; confirm serve --port matches Caddy’s upstream port. |
Service state
| Symptom | Cause | Fix |
|---|---|---|
/healthz returns 503 | Platform DB unreachable, or master key missing. | hiveloom doctor. If master key is missing on a new install, the service writes one on first start; check file perms. |
hiveloom health errors with “connection refused” | Service not running. | sudo systemctl start hiveloom; check journalctl -u hiveloom. |
hiveloom doctor reports “WAL files orphaned” | Crashed in the middle of a write. | Restart cleanly; SQLite recovers. If the service won’t start, restore from the most recent backup. |
Provider credentials
| Symptom | Cause | Fix |
|---|---|---|
Agent replies are empty / provider authentication failed | LLM provider key revoked, expired, or wrong. | hiveloom credential rotate --name <name> --from-env <VAR>. See hiveloom credential. |
model not found errors | Model ID format wrong. | anthropic:<id>, openai:<id>, ollama:<id>. See Store an LLM credential. |
| Replies start truncating mid-sentence | Token budget hit; aggressive compaction. | Inspect hiveloom compaction-log and tune hiveloom agent compaction. |
MCP / chat clients
| Symptom | Cause | Fix |
|---|---|---|
| Claude Desktop shows no tools for the agent | Wrong tenant/agent slug in MCP URL. | Re-derive with hiveloom mcp-identity show. |
| Setup code rejected as expired | 24h window passed. | hiveloom mcp-identity reissue-setup-code <id>. |
| Cursor disconnects after every restart | Bearer header not persisted by the client config. | Re-check the MCP config snippet on Cursor. |
When all else fails
hiveloom doctor --json > doctor.json— captures the on-disk state.journalctl -u hiveloom -n 500 --no-pager > svc.log— recent service logs.hiveloom logs --limit 500 --json > agents.log— recent agent activity.- File an issue at
github.com/FrancescoMrn/hiveloom-rust
with
doctor.json+svc.log+ a redacted snippet ofagents.log. Strip any tenant slugs, hostnames, or user content you don’t want public.