Troubleshooting

Each entry names a symptom and its fix. The linked page has the details.

Machine replaced mid-thread⁠

Capy replaces an expired machine on its next use, from your project's dev environment. Pushed changes and files in Drive survive, but unpushed edits and scratch files don't. Ask Capy to rebuild lost work from the thread history.

Processes gone after sleep⁠

Files survive sleep, but processes and connections don't, because a machine wakes with a cold boot. Put services in your startup script so every wake restarts them. A machine idle for 30 days is deleted with any unpushed work. See sleep.

Setup script failed⁠

The machine still starts, and the thread shows a warning that names the failing repository and phase. Fix the script in the dev environment so the next machine doesn't need repair. initialize runs once per fresh machine, update_after_checkout when the checkout moves, and startup on every boot and wake.

Snapshot build keeps failing⁠

A failed build only slows boot, because machines fall back to full setup. Read the build log under snapshots. The usual cause is a setup script that isn't safe to run twice or depends on something temporary, so fix the script and rebuild.

"Your organization is out of credits"⁠

The balance couldn't pay for the thread's next step. A connected subscription pays only for model tokens, so machine time, images, and reviews still need a balance. Add balance or pick a plan, then message the thread or retry, because it doesn't resume by itself. If auto-reload didn't refill it, see auto-reload.

Thread billed Capy credits⁠

A model with no icon in the picker runs on Capy credits. Your subscription's plan may not include the model, the subscription may be used up, or the thread may belong to a teammate. See keep a model on your subscription.

Codex needs reconnecting⁠

When Codex shows Reconnect needed in Models settings, use Reconnect to sign in again. Codex requires Device code authorization in ChatGPT's security settings. GitHub Copilot and SuperGrok reconnect the same way. If Codex refused a request without saying the connection is invalid, try again in a few minutes or pick another model.

Provider usage limit reached⁠

The subscription for this model hit its usage limit, or HTTP 402 from xAI, means the account behind the connection has no usage left. Wait for the reset, top up with the provider, or pick another model, since reconnecting doesn't help. After the reset, Refresh usage and plan updates a meter that still reads used up.

Key out of quota⁠

A message such as Your OpenAI account is out of quota means the provider account behind the key has no credit. Every thread on that key fails until you fix it. Top up the account, or disable the key in Settings → Models to move its models to the next connection. Then retry the thread.

Key can't run selected models⁠

When Test connection says None of the selected models is available on this key, your provider account can't use the models you ticked. This is often a newer model or a Fast variant. Untick them in the key's Edit sheet, or ask the provider to enable them.

Custom endpoint fails every message⁠

Check access only reads the endpoint's model list. Key accepted, this endpoint does not list its models usually means the base URL under Requests go to is wrong, and most OpenAI-compatible servers expect it to end in /v1. Capy also needs a public https hostname, not localhost or an IP address. If the error says your key's endpoint rejected the request, fix the endpoint or clear the base URL to call the provider directly.

Fast mode fails on your key⁠

Rate limited the request in Fast mode means your provider account doesn't have fast mode. Turn off Fast in the model picker, or enable fast mode with the provider.

Thread ignored CI results⁠

CI results go to the thread that opened the pull request or last pushed to it. A pull request someone opened on GitHub has no thread until a thread pushes to it or someone mentions @capy on it. See which thread owns a pull request.

Thread waiting for a long time⁠

Waiting means the thread expects an event, such as CI, a review, a timer, or a subagent, and the newest thread events show which one. If that event already happened outside Capy, message the thread, because a person's message always wakes it. See what Waiting means.