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:
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. |
| Something else | Choose ⋯ → Report a problem… in the affected task, and send the report (below). |
#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. |
#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. |
| 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.
curl -s http://127.0.0.1:8787/api/health # current versions include "apiVersion": 5Restart 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.