Troubleshooting

Solutions for common Holon issues.

Daemon Issues

Daemon won't start

Symptom: holon daemon start hangs or exits with an error.

Checklist:

# 1. Check if another instance is already running
holon daemon status

# 2. View recent daemon logs
holon daemon logs

# 3. Restart the daemon
holon daemon restart

If the daemon fails to bind to a port, try a different port:

holon daemon start --port 8788

Daemon status shows "stopped" after starting

Check the daemon logs for crash messages:

holon daemon logs

Common causes:

Port already in use by another process
Missing or invalid credentials for the default model
Insufficient disk space or permissions on ~/.holon/

Credential & Model Issues

"No available model" or credential errors

For the fastest repair, run the interactive onboarding wizard:

holon onboard

Run the diagnostic tool:

holon config doctor

This shows which models are available, which credentials are configured, and detailed availability status for each provider/model pair.

API key not recognized

Verify the credential is stored:
```
holon config credentials list
```
For environment variable auth, check the variable is set:
```
echo $DEEPSEEK_API_KEY
```
Verify the provider is registered and the credential profile matches:
```
holon config providers list
```
If using a custom provider, check that --credential-profile matches the profile used in config credentials set:
```
holon config providers get my-provider
```

Model returns errors or unexpected behavior

Verify the model is available:
```
holon config models list
```
Check the current default model:
```
holon config get model.default
```

Try switching to a different model:

holon config set model.default "anthropic/claude-sonnet-4-6"

Agent Issues

Agent not responding

Check agent exists:
```
holon agent model get my-agent
```

Try running with a fresh one-shot:

holon run "test" --agent my-agent --max-turns 1

Agent uses wrong model

Check if the agent has a per-agent model override:

holon agent model get my-agent

Clear the override to fall back to the global default:

holon agent model clear my-agent

Configuration Issues

Config changes not taking effect

Verify the key was set correctly:
```
holon config get <KEY>
```
Check for typos in the key name:
```
holon config schema
```
If changes were made by editing ~/.holon/config.json directly, validate the JSON:
```
holon config list
```
Restart the daemon after config changes:
```
holon daemon restart
```

Config reset to defaults

Check if HOLON_HOME or XDG_CONFIG_HOME is set, which changes the config file location:

echo $HOLON_HOME
echo $XDG_CONFIG_HOME

TUI Issues

TUI display is garbled

Try disabling the alternate screen:

holon tui --no-alt-screen

Or set it in config:

holon config set tui.alternate_screen never

TUI cannot connect to daemon

Verify the daemon is running: holon daemon status
Check the daemon's access mode: holon daemon start --access local is required for local TUI connections

If connecting remotely, ensure the correct --connect URL and --token:

holon tui --connect https://your-server:8787 --token "your-token"

Logs & Diagnostics

Viewing agent task output

Task output is stored under ~/.holon/agents/<agent-id>/task-output/. Each task has a .log file named with its task ID.

Full system diagnostic

holon config doctor

This reports: default model, fallback models, per-model availability with reasons, provider settings, credential status, and retry policy.

Checking runtime configuration

# Full config dump
holon config list

# All available keys with defaults and descriptions
holon config schema

Runtime Performance Diagnostics

Holon tracks granular performance metrics across turn lifecycle phases, provider interactions, tool execution, and persistence. These metrics are cumulative — they cover the entire process lifetime since daemon start.

Retrieving metrics

curl http://127.0.0.1:7878/control/runtime/performance

The response is a JSON snapshot grouped by category:

Metric groups

Group	Key metrics	What to watch
`turn.*`	`turn.total`, `turn.context_build`, `turn.provider_round`, `turn.tool_execution`, `turn.cleanup`	Slow context builds (growing prompt assembly), dominant tool time
`provider.*`	`provider.request_build`, `provider.round_total`, `provider.retry`	High retry counts or latency point to provider issues
`tool.execution`	Cumulative tool timing	Identify tools with unusually high `avg_ms`
`storage.*`	`storage.append_event`, `storage.persist_state`	Persistence slowdowns suggest DB pressure
`projection.agent_state.*`	`tasks`, `timers`, `work_items`, `waiting_intents`, `external_triggers`	State projection overhead per agent
`projection.agents_list`	Agent list projection time	Dashboard/API list latency
`http.*`	Per-route HTTP timing	Slow endpoints, large payloads
`scheduler.*`	`scheduler.poll.all`, `.message`, `.idle`, `.stopped`	Scheduler health (idle ratio, poll latency)

Each metric entry contains:

Field	Description
`count`	Total calls to this phase
`total_ms`	Cumulative wall-clock time
`max_ms`	Worst single call
`avg_ms`	Average call duration

Common diagnosis patterns

High turn.tool_execution — A specific tool is dominating turn time. Check ToolLatencyMetrics on the agent status endpoint to identify the tool.

Frequent provider.retry — The model provider is returning errors or timeouts. Check provider logs (holon daemon logs) and network connectivity.

Growing turn.context_build — Prompt assembly is slowing. This may indicate accumulated memory that needs compaction. Check agent compacted_message_count vs total_message_count.

High scheduler.poll.idle ratio — Normal when no agents are awake. If agents have pending work, check wake hints and wait conditions.

Resetting metrics

Metrics reset on daemon restart. To observe a specific scenario, restart the daemon, reproduce the issue, then capture the snapshot:

holon daemon restart && sleep 2 && curl http://127.0.0.1:7878/control/runtime/performance