Troubleshooting

Confirm you opened the expected Orchestrator data home. All state defaults under ~/.ao; an AO_DATA_DIR or AO_RUN_FILE override can point a development launch at a different daemon instance.

Open the desktop app first. Product CLI commands are thin clients and need the app-owned daemon. A stale ~/.ao/running.json is not enough; Orchestrator also verifies the recorded process.

The primary daemon uses loopback port 3001 by default and fails fast if it cannot bind. Stop the conflicting local process or use a deliberate development AO_PORT override. Never change the bind host to expose the daemon.

Leave the app open briefly so its SSE connection can reconnect and invalidate current queries. If it does not recover, restart the desktop app. The event stream supports replay, but a full app restart is the safest user-level recovery.

Orchestrator retries failed automatic checks with increasing delays, up to four hours. A manual check remains available from the update menu. A failed check does not turn off update checks.

Install the harness, run it once to authenticate, and restart Orchestrator. The desktop daemon inherits a login-shell environment and reuses each provider's installed binary and authentication.

Confirm the selected harness supports native Chat and its binary is authenticated. Chat support depends on the harness and installed version; see the agent capability catalog. Check Settings → Harness and provider version/permission requirements. Choose Terminal UI when the harness lacks Chat support or preflight cannot connect.

New macOS/Linux sessions use detached native PTY hosts. Packaged builds bundle tmux for old sessions/fallback; macOS still validates it. For source runs check configured/system tmux and the native-host launch error. Windows uses ConPTY. See Runtime.

Open the session and answer the pending approval or permission prompt. Orchestrator deliberately does not inject lifecycle messages while a controller is blocked.

Status is derived from activity, termination, controller, and pull-request facts. A failed runtime probe is not treated as death. Reopen the session and inspect its Chat or terminal before killing it.

Use the desktop restore action or ao session restore <session-id>. Restore reuses the same session and worktree when the selected adapter supports recovery. Check that the harness remains installed and authenticated. For a stopped controller on a non-terminated session use ao session resume-agent <id> instead. A disabled interface switch can indicate unavailable native history, an unsupported direction, or pending recovery; inspect its reason before retrying.

The Files pane stops refreshing that session after the daemon confirms its project folder is missing. Restore the folder, then use Retry in Files. Other sessions and hosts continue refreshing normally.

Prompt suggestions wait until the Chat controller is ready and the previous turn is complete. A suggestion can disappear while the agent reconnects or resumes, then return when the conversation is ready again.

Choose an installed, signed-in agent in Harness Settings. If a saved model or effort is no longer supported, review the selected agent default and press Start again. If a branch is checked out elsewhere, enter a new branch name and press Start to confirm it. If the base branch cannot be resolved, set it in Project Settings.

Run gh auth status and confirm the active account can access the repository. GitHub authentication is lazy so an auth failure does not need to block unrelated local session work. For GitLab check token/glab authentication and self-managed-host configuration in SCM setup.

Claim it from the session UI or, inside the worker, run ao session claim-pr <pr-number-or-url>; Orchestrator reads the worker from AO_SESSION_ID. From another shell, use ao session claim-pr <session-id> <pr-number-or-url>.

The SCM observer polls GitHub and respects rate limits and ETags. Check gh auth status, wait for another observation cycle, and open the pull request directly for full raw logs or comment bodies.

Open the review run and use its send action. Reviewer execution and delivery are separate operations so you can inspect findings before changing the worker conversation.

Select a target explicitly with ao preview <url>, or use ao preview start when the worktree contains a valid .ao/launch.json. Orchestrator does not auto-discover a preview for every new worker.

Run ao preview start <configuration> and inspect the returned error. Verify the command and working directory in the session's .ao/launch.json, then run the same command in its worktree shell.

Select the correct session and browser tab. Commands are authorized for the selected session. Temporary profiles are isolated; named profiles deliberately reuse saved browser state. Check the selected profile, and refresh snapshots after navigation. Keep the panel visible for screenshots/human pointer actions. Profile imports have platform-dependent cookie support; a missing login may require signing in again.

Confirm Connect Mobile is enabled and the QR is ready, then use the latest offer/password. Direct LAN needs the same trusted network; remote access needs an advertised, ready secure endpoint. Inspect connector/Tailscale setup failures, and update both apps for identity/contract mismatches. Rotating the password invalidates old credentials.

The current QR carries the host identity, available endpoints, and connection password in a v2 pairing link. Treat it as a bearer credential: do not share the QR or screenshots of it. Rotate the connection password in desktop settings if it may have been exposed.

Do not use a plaintext LAN endpoint on an untrusted network. Use an available secure endpoint from Connect Mobile. Keep the primary daemon private. If mobile push is missing, check phone notification permission, that the phone is still listed under Connected devices, and daemon connectivity.