Common Issues

The quickest fixes for the most frequent problems.

1. Daemon won't start — port in use

# Find what's using port 4200
lsof -i :4200

# Kill it, or use a different port
hoziron start --listen 0.0.0.0:4201

2. Config validation error on startup

# Show current config
hoziron config show

# Fix a specific field
hoziron config set server.listen "0.0.0.0:4200"

# Or edit directly
hoziron config edit

3. Permission denied in container

The container runs as UID 65532 (distroless nonroot). Ensure the volume is writable:

# Docker
docker run -v hoziron-data:/data ...

# Or with explicit ownership
docker run -v ./local-data:/data --user 65532:65532 ...

In Kubernetes, set fsGroup:

securityContext:
  fsGroup: 65532

4. Provider key not working

# Test the key
hoziron config test-key anthropic

# Verify the env var is set
echo $ANTHROPIC_API_KEY

# Re-set it
hoziron config set-key anthropic

Keys are resolved at request time — if you changed the env var, restart the daemon if it was set before the process started.

5. Agent won't respond to messages

Check: is the agent actually running?

hoziron agent status <agent-id>

If it's in Created state, start it:

hoziron agent start <agent-id>

6. "Cannot apply 'start' to agent in Running state"

The agent is already running. Check its current state:

hoziron agent status <agent-id>

7. Registry unreachable

hoziron catalog registry test

Check network connectivity and auth tokens.

8. CORS errors from dashboard

CORS must be configured if the dashboard connects directly:

[server.cors]
allowed_origins = ["https://dashboard.company.com"]
allow_credentials = true

Cannot use wildcard * with allow_credentials = true.

9. Route panic on startup (axum)

If you see a panic mentioning route syntax or path parameters: ensure path parameters use {param} syntax (axum 0.8), not :param.

10. Health check shows degraded

hoziron health --json

Check which subsystem is degraded and see the specific troubleshooting page:

Related: