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 doctor

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

# Machine-readable output
hoziron doctor --json

Check daemon status:

# Quick health check
hoziron health

# Detailed status with agent counts
hoziron status

# View recent logs
hoziron logs --lines 100

# Follow logs in real time
hoziron logs --follow

What's the problem?

Symptom	Go to
Something obvious and quick	Common issues
Provider auth failure, circuit breaker, unreachable	Provider issues
Agent stuck, wrong state, not responding	Agent issues
High memory, slow responses	Performance
Kernel recovery failed, data corruption	Recovery

Useful commands at a glance

hoziron doctor --repair        # Auto-fix common problems
hoziron health --json          # Structured health report
hoziron security status        # Check security config
hoziron security verify        # Verify audit chain
hoziron system info            # Full system info for bug reports

Related: