Troubleshooting

Something went wrong? Don't worry — most issues have straightforward fixes. Let's get you back on track.

Quick diagnostics

Before diving into specific issues, run the built-in diagnostics:

# Comprehensive health check
hoziron-cli doctor

# Auto-fix common issues (creates missing dirs, repairs config)
hoziron-cli doctor --repair

# Machine-readable output
hoziron-cli doctor --json

Check daemon status:

# Quick health check
hoziron-cli health

# Detailed status with agent counts
hoziron-cli status

# View recent logs
hoziron-cli logs --lines 100

# Follow logs in real time
hoziron-cli logs --follow

What's the problem?

Symptom	Go to
"No carrier licence loaded", licence expired/invalid	Common issues
Daemon refuses to start ("Refusing to start ... auth.mode="disabled"")	Common issues
Config validation error on boot	Common issues
Provider auth failure, circuit breaker open, unreachable endpoint	Provider issues
Agent stuck in `Suspended`, activation fails, not responding	Agent issues
High memory, slow responses, capacity planning	Performance
Kernel recovery exhausted, data corruption, backup/restore	Recovery

Useful commands at a glance

hoziron-cli doctor --repair        # Auto-fix common problems
hoziron-cli health --json          # Structured health report (includes latency_p95_ms)
hoziron-cli security status        # Check security config (auth mode, TLS)
hoziron-cli security verify        # Verify audit chain (Merkle hash chain)
hoziron-cli system info            # Full system info for bug reports
hoziron-cli licence status         # Carrier licence status, expiry, budget usage
curl .../gateway/pools         # Per-provider live reachability (see providers.md)

Related: