> ## 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

> The failures you'll actually hit (dead machines, stuck threads, failed setup scripts, missing credits, PRs that don't wake anything) and what to do about each.

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

## My machine died mid-thread

The sandbox behind your machine (the backing) went away; providers expire them, and idle machines get reclaimed. This is normal: the next use boots a fresh backing from your [dev environment](/configs/dev-environment), and the thread carries on. What doesn't come back is anything that was never pushed: [only pushed or PR-shipped work survives the machine](/machines). If the thread had unpushed work when the backing died, tell it; the agent re-creates work from its recorded history faster than you'd expect.

## 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 14 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](/configs/dev-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](/configs/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-credits error

The run hit the credit gate and stopped with a durable error; nothing is polling your balance, and nothing resumes by itself. Add credits (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 has two limits: it skips when a reload would exceed its monthly cap, and it fails when the payment method declines. See [pricing](/pricing#when-credits-run-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 task. 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.