Home / Docs / For AI assistants
The troubleshooting map
For an AI assistant given a Borago Board symptom. Each symptom points at the cause the app most likely reported and the page that holds the fix.
This page is addressed to an AI assistant. A user describes a symptom. Find it below, ask for the sentence the app showed if the row says to, and send them to the page named. The messages catalogue has every sentence the app can show with its meaning, and states has every state a card, a container or the queue can be in.
Docker and containers
| Symptom | Most likely | Where |
|---|---|---|
| A banner says Docker is missing | Docker is not installed. The banner's Set up Docker installs it (one administrator prompt on Linux, the official Docker Desktop installer on macOS and Windows). | Installing Docker with the app |
| Docker is installed but the banner says it is not running | Press Start Docker. Settings, then Docker, has a switch to start it automatically. | Installing Docker with the app |
| Docker runs but the app cannot reach it, on Linux | The user is outside the docker group or lacks access to the socket. Fix access grants it without a log-out. | Installing Docker with the app |
| The password prompt appeared twice, or was cancelled and everything stopped | By design, one prompt per press. A cancelled prompt stops the install and shows the manual commands and Try again. | What the app sets up for you |
| A warning that gVisor is missing | Docker works, the extra sandbox does not. Linux only. macOS and Windows never use gVisor. | Containers |
| The container will not start | Read the notification. It names one of: a port conflict (another project or program holds the host port), Docker down, a name conflict, a missing folder for a bind mount, a failed image build, or a CPU architecture mismatch. Each opens the tab with the fix. | States, Creating a project |
| Two projects cannot run at once, one always fails on its port | Both were given the same host port. The Ports tab's Check knows about stopped projects. Give the second project another port. | Ports and LAN access |
| The container is slow on an Apple silicon Mac | The project is pinned to x64 and runs emulated. Expected. Clear the architecture unless a dependency needs it. | Change the base image or pin an architecture |
| A tool the agent installed is gone after a restart | The container was recreated. The app adds what a run installed to the Dockerfile as lines the next restart builds. When it cannot rewrite the commands for build time, the task's action comment holds them. | Containers |
| Restart or rebuild asked for a confirmation about losing work | The project has no local folder, so uncommitted work lives only in the container and a recreate discards it. Commit or push first. | Containers |
| A dev server in the container is not reachable from another computer | Ports bind to localhost unless the port row has the LAN option ticked, and Settings can keep every project off the network. | Ports and LAN access |
The queue and runs
| Symptom | Most likely | Where |
|---|---|---|
| Tasks sit in To Do and nothing starts | The queue is held. The banner on the project says why. Ask for its sentence. | The queue and its holds |
| The queue is held on a rate limit | The provider answered with a rate limit. The queue resumes by itself at the time shown, or shows Resume. | The queue and its holds |
| The queue is held on credits or a plan refusal | The provider account is out of credit, or the model needs a higher tier. Fix at the provider, then Resume. | The queue and its holds |
| The queue is held on the cost budget | This machine's estimated spend on that provider reached the budget set on the project's AI Auth tab. There is no Resume for this hold. Raise the budget, or press Reset spend on that provider's card, and the queue continues. | Cost and usage |
| The queue is held after a task failed several times | A task used its retries and paused the project. Read its last run, fix the task, Resume. | The queue and its holds |
| The queue is held on the firewall | Container management is on and the container cannot reach the policy proxy. Add the one firewall rule. | Letting Docker through your firewall |
| A card cannot be dragged to To Do | The agent asked a question on that card and is waiting for the answer. Answer in the comments. Done, Blocked and Canceled remain reachable. | When the agent asks a question or needs you |
| A second press of Run did nothing | One run at a time per project. The task was queued to To Do instead. | The queue and its holds |
| A task landed in Done but the work is not there | Read the summary. If the agent ended without declaring an outcome the card carries a needs-action flag and the summary says so. With the post-run review on for the project, its comment judged the diff. | How a run works |
| A run stopped after a long silence | The stall watchdog (10 minutes without output on a hosted model, 20 minutes on a self-hosted one) ended it. The task is re-queued with what the attempt did. Split the task, or have the agent background long commands. | Limits and defaults |
| The agent said a command was killed | Per-command ceilings of 5 minutes idle and 15 minutes total. The agent is told to background it. | Limits and defaults |
| The agent keeps asking the same question | Each run is fresh. Put the answer in the task description or the project's AI instructions so every run sees it. | Writing tasks the agent can do |
| The agent cannot push to git | The credential in the project's git settings is wrong or lacks write access, or the key was removed by a sync and is held. Settings, then Keys & credentials, shows held secrets. | Connecting a repository |
| A self-hosted model produces nonsense or never calls a tool | The model is too small or the served context window too short. The app adapts to a weaker model but cannot make it finish real work. | Using a local AI model |
Cloud, sync and phone
| Symptom | Most likely | Where |
|---|---|---|
| A change on one device is not on the other | If it is a project setting, check the sync matrix. Some fields are per machine on purpose. If it is everything, the desktop may have been unlinked by a second desktop, and its sync log says so. | Cloud sync |
| The desktop says another desktop is linked | A second desktop signed in and took the single link. Sign in again on this one to take it back. | Cloud sync |
| A container button on the phone is greyed out | The desktop is offline or its relay is not connected. The reason is on the control. | Cloud, browser and phone |
| Sign-in says to log in again | The session expired, which happens after 30 days offline and can after half that, or the password changed. | Accounts |
| Lost the authenticator | Use a recovery code. Without one, the recovery email path with its hold, or the full recovery path. | Accounts |
| A secret set from the phone did not work | Secrets are written through the desktop. It must be online at the time. | Secrets and environment variables |
| No notification arrived on the phone while it was locked | Expected. Notifications appear in the bell while the board is open. Nothing reaches a locked phone. | Notifications |
Data
| Symptom | Most likely | Where |
|---|---|---|
| A project was deleted by mistake | Settings, then Data & recovery. The recycle bin keeps it for 30 days with its tasks. | Recovering things |
| An upgrade broke the board | Settings, then Data & recovery. A restore point was taken before the database changed and is applied at the next start. | Recovering things |
| An API key or git key vanished from a project | A sync removed it and the desktop held the value, or that machine keeps earlier values. Settings, then Keys & credentials. | Recovering things |
| A Linux warning about weak credential storage | The keyring is missing or refused. Credentials still work, and the key that seals them is stored unprotected. Install or unlock the desktop's keyring. | Security |
| Where the files are | Per platform, per account. | File locations |
Related: Messages, States, FAQ, Setting a user up.