<!-- Source: https://console.uubright.com/docs/troubleshooting/ -->
# Troubleshooting

On a Mac with the uuBright Console app, start with [On a Mac](#on-a-mac-this-mac). On a
server, check one layer at a time: the service, then your connection, then Claude,
then Git. Keep the SSH tunnel from [Getting started](https://console.uubright.com/docs/getting-started/) working while
you diagnose anything else.

Two commands answer most questions:

```sh
npm run doctor -- --service                           # tools, resources and the running service
tmux capture-pane -p -S -200 -t =ccr-cloud:           # the control plane's recent output
```

## On a Mac (This Mac)

The uuBright Console app runs its own service on your Mac, as your macOS account.

| Symptom | What to do |
|---|---|
| Where are the logs? | Choose **View logs** in the **uuBright Console** menu (or on the start screen). The service's log is `~/Library/Application Support/CCR Cloud/service.log`. A task's own log is `~/Library/Application Support/CCR Cloud/host/<task id>/runner.log`; the task id starts with `s-` and appears in the task's address. |
| The first start doesn't finish | Keep the window open; a slow disk or a proxy can make it take a while. Then use **View logs**, and **Retry**. |
| Tasks fail after working before, or say you aren't signed in | The Claude Code or Codex login on this Mac has expired. In Terminal, run `claude` (or `codex login`) and sign in again, check it answers a prompt, then **Resume** the task. |
| Tasks stop or the phone can't reach the Mac | The Mac went to sleep, lost its network, or you logged out. uuBright Console keeps the Mac awake while tasks run (**Keep Mac awake while tasks run** in the **uuBright Console** menu), but not while a task waits for your approval, and closing the lid sleeps it anyway. Wake the Mac, then **Resume** any task that stopped. |
| The app shows **Restore This Mac access** | Its saved sign-in for the local service no longer works, for example after an update. Choose **Reconnect This Mac…**, then **Confirm reconnect**. It replaces only this Mac's owner token; your tasks, pairings, settings and the service's identity stay. |
| A Codex task fails with "Codex provider … needs …" (or "Missing environment variable") | Your `~/.codex/config.toml` uses a model provider whose key is in an environment variable, and uuBright Console can't find it. Set it in your shell profile, for example `export R9S_TEST_API_KEY=…` in `~/.zshrc`, choose **Restart uuBright Console**, then **Resume** the task. **Setup check** shows what uuBright Console read from your shell. See [Custom model providers](https://console.uubright.com/docs/codex/#custom-model-providers). |
| Something else | Choose **⋯ → Report a problem…** in the affected task, and send the report ([below](#report-a-problem)). |

## Setup and the service

| Symptom | What to do |
|---|---|
| Setup reports a missing tool | Install it for the service user, then run setup again. |
| `--start` can't verify the API | Read the control plane output (above). Check the port in `server.env` and look for an old process on it: `ss -ltnp 'sport = :8787'`. |
| Setup says Claude isn't found | Make sure `claude` is on the `PATH` of the shell that runs setup. |
| Host is slow or tasks die | Run `npm run resources` and run fewer tasks at once. See [Check host resources](https://console.uubright.com/docs/operations/#check-host-resources). |

## Connecting

| Symptom | What to do |
|---|---|
| The browser can't reach `localhost:8787` | Keep the laptop SSH tunnel running, and check you opened the same local port. |
| The token is rejected | Read the token from the same server and data directory as the address you opened. Each uuBright Console instance has its own token. |
| HTTPS address doesn't load | Check the service and your connection process (Tailscale Serve or the Cloudflare tunnel) separately. Both must be running. |
| Phone works only on some networks | Check Tailscale or Cloudflare reachability on that network. Use the laptop tunnel meanwhile. |

## Claude

| Symptom | What to do |
|---|---|
| A scratch task fails or never replies | First check the task's status and any pending approval. Then, on the server as the service user, run `claude` and complete login, or test model access with `claude -p "Reply OK"`. |
| It worked before, now fails to authenticate | Renew the login through Claude Code as the same user. Check `CLAUDE_CONFIG_DIR` if you use a custom one. |
| A task fails with "Claude Code was not found" (or Codex) | The task couldn't find the agent's executable. Find it with `command -v claude` as the service user. Then either add its directory to the service's `PATH` or set `CLAUDE_BIN` (`CODEX_BIN` for Codex) to its full path in `server.env`. Restart the service, then **Resume** the task. Resume brings an existing host task's `PATH` and executable settings up to date with the server's. The messages you already sent are delivered then. |
| Task details | Read `DATA_DIR/host/SESSION_ID/runner.log`. |

GitHub checks and network probes don't test model access. The scratch task is the
end-to-end check.

## Repositories

| Symptom | What to do |
|---|---|
| "Repository not found" when adding a URL | Use an SSH URL for an SSH key, or HTTPS for a credential helper. Then run `npm run github -- --repo URL` on the server. Failed checks show a diagnostic ID; find it in the control plane output. |
| A checkout is missing from **Find a repository on this server** | Type its name or path to search the server beyond the initial 100 results, or select **Rescan repositories**. If results are incomplete, narrow the search roots. Check that `CCR_CLOUD_REPO_ROOTS` uses absolute paths, and that the checkout is within three levels and not behind a symlinked folder. Or [add it by its path](https://console.uubright.com/docs/repositories/#add-a-repository-by-path). |
| A task can't start in a new repository | Make an initial commit first. |
| Cloning works in your shell but not in tasks | Your SSH agent may have been forwarded from your laptop. Use credentials that stay on the server. |

## The app and server don't match

If **Server setup** is unavailable, project routes return `not found`, or a new
feature is missing after an update, the browser has new files but an older control
plane is still running. Pulling code doesn't reload it.

```sh
curl -s http://127.0.0.1:8787/api/health   # current versions include "apiVersion": 5
```

[Restart the service](https://console.uubright.com/docs/operations/#restart-the-service), then refresh the browser.

## Report a problem

Open the task where it went wrong, then choose **⋯ → Report a problem…** at the
top right. Describe what you did and what happened, and choose **Build report**.

The report is one JSON file with:

- the app build, the core's version, your operating system and browser;
- the workspace and task ids, and the task's title and state;
- the last 500 lines of the server log and of the task's runner log;
- the task's last 50 events;
- the page's recent errors;
- your description.

Tokens, keys and other secrets are replaced with `[redacted]` before you see it:
your owner and device tokens, the CCR client key, the GitHub token, plugin
secrets, the task's environment, values like `sk-…` or `smgo_pat_…`, and any long
random-looking string. The preview shows every line of the file. Read it, choose
**Download report**, and email the file to
[support@uubright.com](mailto:support@uubright.com). Nothing is sent for you.

!The report's preview, with every secret replaced

**More → Report a problem…** (on a phone, or in a chat workspace) and the ⋯ menu on
a page without a task build a report with the server's log and no task. Paired
devices can build reports too.

## Still stuck?

Use **Report a problem** (above) from the app, or email
[support@uubright.com](mailto:support@uubright.com) with the steps to reproduce.
Leave out tokens, `server.env` and private logs.
