# Troubleshooting

Use this page when ZoneGaze Flow does not launch, cannot start an agent, or does not show the expected project state.

## The Board Does Not Load

Try:

1. Refresh the page.
2. Confirm the local runtime is running.
3. Use the Mac recovery screen, tray status, or CLI output to check the runtime URL.
4. Confirm the port is not occupied by another process.
5. Restart the runtime.

Use the local URL shown by the CLI output when launching from the terminal.

## The Runtime Is Offline

In the Mac app, use the recovery screen or tray status when the runtime is offline.

![Mac Matrix dashboard](./assets/screenshots/mac-desktop-dashboard-current.png)

If the runtime is offline, restart it from the recovery screen or tray. If it fails, read the displayed status and check terminal logs.

If the runtime becomes unreachable after the app has opened, use the recovery screen to restart it or attach to an external runtime.

![Mac disconnected runtime recovery](./assets/screenshots/mac-desktop-disconnected-current.png)

## A Project Is Missing

Use Add Project. If the folder picker is unavailable, enter the path manually.

Remote or headless environments may not support native folder pickers. Manual path entry is the expected fallback.

## An Agent Cannot Start

Check:

- the selected agent is installed
- provider authentication is complete
- required CLI commands are on PATH
- the project is readable
- the Git base ref exists
- no required secret is missing

Open Settings and inspect the agent section.

![Agent settings in the settings dialog](./assets/screenshots/web-settings.png)

## Android Setup Is Blocked

The Android app needs the owned Zone Terminal setup to complete before runtime-backed plugins can start.

![Android permissions dashboard](./assets/screenshots/android-permissions-dashboard.png)

If Android setup is blocked:

1. Install or update the ZoneGaze Matrix APK from the trusted project channel.
2. Open the app and keep it in view while automatic runtime setup runs.
3. Open **Runtime** to watch setup progress or retry a failed setup.
4. Save a launch folder if the plugin needs project storage.
5. Start only the plugin/runtime surface you are opening.

If automatic setup repeatedly fails, confirm the emulator or device has enough free internal storage for the bundled runtime package and inspect the Runtime diagnostic shown by the app.

![Android setup failure](./assets/screenshots/android-setup-package-failure.png)

## Terminal Shows Old Output

The terminal can persist session output. Clear or restart the terminal if old commands are distracting.

![Terminal panel](./assets/screenshots/web-terminal.png)

## Git State Looks Wrong

Open the Git history view and refresh.

![Git history view](./assets/screenshots/web-git-history.png)

Check:

- current branch
- upstream state
- changed file count
- untracked files
- whether the task is using a worktree

## Still Blocked

Collect:

- platform and app version
- project path
- runtime status
- exact error message
- relevant terminal output
- what you expected to happen

Then share the smallest reproduction that does not include secrets.
