> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

Each entry names the symptom, what actually happened, and the fix. The owning page has the full mechanics.

## My machine died mid-thread

An expired or reclaimed sandbox is replaced on the next use using the project's [dev environment](/environment). Pushed repository changes and files saved in [Drive](/drive) survive [machine replacement](/machines); unpushed checkout edits and scratch files don't. Ask Capy to reconstruct lost work from the thread history.

## My files are gone after the machine slept

Sleep persists the filesystem, so files survive sleep; what dies are processes, memory, and connections, because resume is a cold boot. If a dev server was running before sleep, it isn't after; `startup` scripts re-run on wake to bring services back. A machine asleep past 2 days moves to colder storage (still resumable); at 30 idle days it's deleted, and unpushed work goes with it. Details on [machines](/machines#sleep).

## My setup script failed

The machine still comes up: setup failure degrades, it doesn't block. The thread gets a workspace warning naming the failing repo and phase, and the agent usually repairs the workspace by hand for that run. Fix the script itself in the [dev environment](/environment) so the next machine doesn't need repairing, and check the phase: `initialize` runs once per fresh machine, `update_after_checkout` when the checkout moves, `startup` on every boot including wake.

## My snapshot build keeps failing

Snapshot builds never gate work: machines fall back to full setup, so a failing build only costs boot speed. Read the build's log from the [snapshots](/environment#snapshots) surface or ask Capy for it; the usual cause is a setup script that isn't idempotent or depends on something transient. Fix the script, then trigger a rebuild or wait for the next content change.

## A run stopped with an insufficient-balance error

The run hit the balance gate and stopped with a durable error. Nothing polls your balance, and nothing resumes by itself. Add balance (or let [auto-reload](/admin/billing#auto-reload) do it), then message the thread or hit retry; it picks up from its recorded history. Auto-reload skips when a reload would exceed its monthly cap, and fails when the payment method declines. See [models & pricing](/models-and-pricing#when-your-balance-runs-out).

## CI failed but my thread never reacted

Almost always: the PR wasn't opened by the thread. Only a PR the agent opened through its own machinery subscribes the thread to that PR's CI, review, and merge events; a PR someone opened by hand with `gh pr create` delivers none of that. Ask the agent to take over the branch and open the PR itself, or relay the CI result manually. See [pull requests](/pull-requests).

## The thread has been "waiting" for ages

Waiting means an external event owns the next move: CI still running, a review round in flight, a timer, a subagent. Look at the newest thread events to see which. If the awaited thing already happened out-of-band (you merged manually, CI was cancelled), just message the thread and say so; a human message always wakes it.

## Capy doesn't respond in my archived thread

Archive is dormant by design: every event still lands as pending context, but nothing wakes the thread except a message from a person, which unarchives it and resumes with everything that accumulated. Unarchive alone reopens the lists without starting a run. See [working in threads](/threads#archive-is-dormant).

## The exposed port URL stopped working

Exposed URLs serve a live process on an awake machine. When the machine sleeps, the process is gone (cold-boot rule) even after the machine wakes. Ask the agent to restart the server, or put it in `startup` so every wake brings it back.

## An MCP server's tools aren't available

Check scope and credentials in order: the server must be enabled for the project, and it needs a live connection. Personal connections beat shared ones, and an expired OAuth grant flips the server to needs-auth, which removes its tools until someone reconnects. Reviews never see MCP tools regardless; only the capy agent uses them. See [MCP](/integrations/mcp).

## Still stuck

[Contact support](/support) and include the thread reference (like `CAPY-42`), which appears in the thread's header.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.