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

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