Troubleshooting

Resolve the highest-frequency daemon failure patterns with deterministic recovery steps. For incidents outside this guide, inspect opta daemon logs first and escalate with the exact error trace.

Daemon Exits Immediately

If opta daemon start exits without error output, the most common cause is a port conflict.

Port in Use

The daemon tries to bind to port 9999. If that port is taken, it scans ports 10000 through 10020. If all ports are occupied, the daemon fails to start.

COMMAND   PID  USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
node    12345  matt   22u  IPv4  0x...  0t0  TCP localhost:9999 (LISTEN)

If another process owns the port, either stop that process or configure the daemon to use a different port range:

WebSocket Drops

WebSocket connections can drop for several reasons. The most common is the LMX server becoming unreachable during inference.

LMX Unreachable

If the daemon cannot reach the LMX server at lmx-host.local:1234, it will emit a turn.error event with code LMX_UNREACHABLE. The WebSocket connection itself stays open, but inference fails.

{"status":"ok"}

{"ready":true,"model":"qwen3-30b-a3b"}

Permission Requests Hang

If a turn appears stuck, it may be waiting for a permission approval that was never resolved. This happens when a client disconnects while a permission.request event is pending.

To unblock the session:

State File Corrupt

If the state file at ~/.config/opta/daemon/state.json becomes corrupt (e.g., due to a power loss during write), the CLI will fail to connect to the daemon.

Fix: delete the state file and restart the daemon.

Crash Recovery

If the daemon crashes, the CLI automatically detects the stale state file on the next command. The ensureDaemonRunning crash guardian performs these steps:

• Reads the PID from state.json
• Sends a signal-zero check to verify the process is alive
• If the process is dead, removes the stale state file
• Spawns a new daemon with a fresh token
• Retries the original command

This happens transparently — in most cases, you will see a brief delay while the daemon restarts, then your command proceeds normally.

opta doctor

The opta doctor command runs a comprehensive diagnostic check across the entire Opta Local stack:

Checking daemon...        ● running (pid 12345, port 9999)
Checking LMX...           ● reachable (lmx-host.local:1234)
Checking model...         ● loaded (qwen3-30b-a3b)
Checking config...        ● valid
Checking permissions...   ● ok

All checks passed.

Use opta doctor --fix to attempt automatic fixes for common issues (stale state files, dead processes, missing config directories):

Log Analysis

The daemon log at ~/.config/opta/daemon/daemon.log is your primary debugging tool. Key patterns to look for:

# Successful start
[10:00:01] INFO  daemon started on 127.0.0.1:9999

# LMX connection failure
[10:00:05] ERROR lmx preflight failed: ECONNREFUSED lmx-host.local:1234

# Permission timeout
[10:05:00] WARN  permission request perm_001 timed out (5m), auto-denying

# OOM in tool worker
[10:10:00] ERROR tool worker crashed: heap out of memory

# Session directory creation race
[10:00:02] WARN  session dir already exists, skipping mkdir

Reset Everything

If targeted remediation fails, run a controlled full daemon reset. This sequence stops the daemon, clears daemon state artifacts, and starts a clean process while preserving session history.