Troubleshooting

On a Mac with the uuBright Console app, start with On a 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 working while you diagnose anything else.

Two commands answer most questions:

SHELL
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.

SymptomWhat 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 finishKeep 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 inThe 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 MacThe 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 accessIts 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.
Something elseChoose ⋯ → Report a problem… in the affected task, and send the report (below).

#Setup and the service

SymptomWhat to do
Setup reports a missing toolInstall it for the service user, then run setup again.
--start can't verify the APIRead 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 foundMake sure claude is on the PATH of the shell that runs setup.
Host is slow or tasks dieRun npm run resources and run fewer tasks at once. See Check host resources.

#Connecting

SymptomWhat to do
The browser can't reach localhost:8787Keep the laptop SSH tunnel running, and check you opened the same local port.
The token is rejectedRead 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 loadCheck the service and your connection process (Tailscale Serve or the Cloudflare tunnel) separately. Both must be running.
Phone works only on some networksCheck Tailscale or Cloudflare reachability on that network. Use the laptop tunnel meanwhile.

#Claude

SymptomWhat to do
A scratch task fails or never repliesFirst 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 authenticateRenew 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 detailsRead 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

SymptomWhat to do
"Repository not found" when adding a URLUse 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 serverType 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.
A task can't start in a new repositoryMake an initial commit first.
Cloning works in your shell but not in tasksYour 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.

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

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. 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 with the steps to reproduce. Leave out tokens, server.env and private logs.