# Troubleshooting

## Runtime Does Not Open

- Direct Mac app: open `ZoneGaze Matrix.app`. It should start or attach to the runtime and open the Matrix dashboard directly. From the tray, use **Start Server** / **Restart Server**. If the recovery screen appears, choose **Restart runtime**.
- Direct Android app: keep the app open while owned Zone Terminal setup finishes before tapping **Start**.
- CLI path: ZoneGaze Flow requires **Node.js 22 or newer**. A `SyntaxError: Unexpected token 'with'` (from `cli-spinners`) means you are on an older Node — switch to Node 22+ (for example `nvm use 22`) and retry.
- If browser opening fails on Linux, open the printed URL manually.
- Use `--no-open` when browser launch is not available.
- If the intended port is already in use, pass a different `--port` or `--port auto`.
- For this repo, verify `http://127.0.0.1:4217/demo-website`.

## Project Cannot Be Added

- Confirm the path exists.
- On remote/headless systems, use manual path entry or the remote file browser.
- If the folder is not a git repo, decide whether to initialize git.
- On Android, choose shared folders with the native folder picker before browsing external storage from the runtime.

## Direct App Install Fails

- Mac: confirm the DMG came from the trusted project distribution channel and matches the Mac CPU architecture.
- Mac: if the server dashboard is blocked, check whether another process owns `127.0.0.1:3484`; the packaged app should start on the next free runtime port automatically.
- Android: install or update the ZoneGaze Matrix APK from the trusted project distribution channel.
- Android: open **Runtime** and confirm the automatic Zone Terminal setup finishes.
- Android: inspect the Runtime diagnostic in the app when automatic setup fails, then use **Retry runtime setup**.

## Agent Does Not Start

- Check Settings for detected agents and selected agent.
- Confirm the binary is available on `PATH`.
- For Cline, configure provider, model, API key or OAuth, and MCP settings as needed.
- Review board card errors and task session summaries.

## Terminal Or Chat Looks Stale

- Refresh the page. PTY state is server-side and should reconnect.
- Switch away and back to the task.
- For native Cline, reload the task chat session if the UI exposes that action.
- If reconnect repeatedly fails, inspect runtime logs and [operations runbook](../operations/runbook.md).

## Diffs Look Wrong

- Compare all changes versus last-turn changes.
- Confirm the task worktree still exists.
- Check generated/untracked path filters.
- For binary files, use the file tree and working-copy summary rather than expecting text hunks.

## Git Actions Fail

- Confirm the task worktree branch is valid.
- Check for git lock files or uncommitted/stashed changes.
- Fetch before pull or push when branch state is stale.
- Do not force-push from ZoneGaze Flow.

## Remote Access Fails

- Confirm the server is bound to the intended host.
- Confirm passcode authentication state.
- Check origin and host validation.
- Avoid public tunnels from this repo; local agents should serve only the canonical local URL.

## More Detail

- [Operations runbook](../operations/runbook.md)
- [Direct Mac application](../platforms/direct-mac-application.md)
- [Direct Android application](../platforms/android-application.md)
- [Runtime API reference](../reference/runtime-api.md)
- [Generated source reference](../reference/generated/source/README.md)
