Troubleshooting

Common failure modes, diagnostic steps, and fixes for the desktop client, the gateway, and the plugins.

Most ClosedLoop.ai failures fall into one of a few categories. This page is the first place to look when something goes wrong.

Tray says `error` or `degraded`

Tray error

startup failed
open the main window; the Dashboard shows the technical detail
check the in-app logs under desktop:get-logs (exposed in the UI)
common causes: port conflict outside the fallback range, missing API key, malformed settings

Tray degraded

the cloud socket is disconnected or awaiting hello-ack
local operations still work
the recovery timer forces a full reconnect after 2 minutes; wait or force one with Pause/Resume

the operation tried to touch a path outside the sandbox or inside a hard-denied path
confirm sandboxBaseDirectory includes the target path
check for symlinks that escape the sandbox; paths are canonicalized via fs.realpathSync.native
remember hard-denies apply even inside the sandbox: ~/.ssh, ~/.gnupg, ~/.aws, ~/Library/Keychains, /etc, /bin, /sbin

probe order: 19432 → 19433 → 19434 → 19435
confirm the active port at ~/.closedloop-ai/electron-port
if all four ports are busy, the tray goes error; free a port or quit the conflicting process

the desktop spawns $SHELL -ilc to extract the real PATH; if your shell init does not export the binary, spawn will fail
telemetry emits preflight.binary_not_found or preflight.spawn_failed
override the binary path at Settings → Binary paths or via PATCH /api/gateway/settings/binary-paths

check state.json for the current phase and status
if status is AWAITING_USER, you have an open checkpoint (answer questions or confirm changes with /code:amend-plan)
if an agent is looping on a promise, check the hook logs and the validation script output
cap runtime with CLOSEDLOOP_MAX_ITERATIONS (default 10)

the plan structure violates plan-schema.json
read the validator output
common issues: missing acceptance criteria, mismatched array lengths, invalid task types
fix the plan and relaunch; the validation script will revalidate

a learning_agent did not acknowledge and capture learnings
subagent-stop-hook.sh will re-run the agent up to 2 times
if it still fails, check the agent prompt and self-learning:learning-quality skill availability

Log	Location
In-app ring buffer (500 entries)	`desktop:get-logs` IPC, shown in Logs tab
Electron stdout/stderr	console, tagged `[tag][HH:MM:SS.fff]`
Symphony loop subprocess	`logPath` and `jsonlPath` per job
Activity Log	`desktop-activity-log.json`
Port discovery	`~/.closedloop-ai/electron-port`
Gateway identity UUID	`<userData>/gateway-identity.json`

All under app.getPath("userData"):

quit and relaunch the desktop client; the BootRecoveryService reattaches live jobs and finalizes dead ones
check ./plugins/code/scripts/preflight-check.sh under plugins/self-learning/scripts/ (bundled with the plugin) for Python, jq, awk, git, and PyYAML presence
rerun the plugin install script to restore any missing plugin files