# Run books

> What to do when something goes wrong, step by step.

What to do, step by step, when something goes wrong. Each run book uses only what you can see and do yourself, in LightHouse and in your own account.

## An agent is failing

1. **Find it.** **Agents → Hub**, filtered to `failing`, or `GET /api/v1/agents?status=failing`. `GET /api/v1/attention` lists it too.
2. **Open its last run.** The [run map](/build/run-map/) shows which step failed, its status, its model and its duration.
3. **Check its dependencies.** An agent whose `needs` failed is `skipped`, not failed: fix the first failure in the chain.
4. **Check the safeguards.** **Security and context → Safeguards**, or `GET /api/v1/refusals`: a refusal for a cap, a kill switch, screening or grounding stops a call by design.
5. **Check the deployment.** `GET /api/v1/health`, or the [`health`](/mcp/tools/health/) tool: a gateway or job reported `down` or `degraded` explains every agent on it.
6. **Stop it while you look**, if its failures cost or annoy: a handler pauses it (`agent.pause`). See [Suspension](/operations/suspension/).
7. **Fix and release.** A change to the card or its code goes through the release gate; to go back, make the last version that passed current. See [Versioning and rollback](/build/versioning/).

## A cap is reached

1. **See which.** `GET /api/v1/budgets` lists each scope’s cap and spend; `GET /api/v1/refusals` shows calls refused for it.
2. **Decide whether the cap is right.** A cap is reached by design when an agent loops or a job grows. Check the agent’s runs and cost per run in **Spend → Cost** first.
3. **To raise it**, a person does: a handler’s `budget.set` for one agent (raising needs a role your deployment’s policy names, and never goes past its ceiling), or a `client_admin` changes the limit under **Spend → Limits**. A machine key cannot.
4. **To keep it**, do nothing: calls past the cap are refused until the period resets (UTC day or month), or the cap is raised.

See [Limits and alerts](/operations/limits-and-alerts/).

## A connector stops indexing

1. **Check the card.** **Setup and admin → Connectors**: a `failing`, `expiring` or `disconnected` state, and the failures over the last 7 days.

2. **Check the knowledge base.** **Agents → Knowledge**: the last successful ingest, and failures by class (`auth`, `permission`, `not_found`, `rate_limited`, `timeout`, `network`, `parse`, `config`).

3. **By class:**

   - `auth` or `permission`: the credential expired, was revoked or lost access. Replace it in your secret store; for a LightHouse connection, connect again.
   - `rate_limited` or `timeout`: the provider slowed the pull. It retries on its next schedule; widen the schedule if it persists.
   - `config`: the source card is wrong (a missing repository, a bad URL). Fix the card.
   - `parse`: an item could not be read. For a folder, a file type it does not accept stops the pull, naming the file.

4. **Run it once by hand** and read its note: `written N, unchanged N, quarantined N, removed N`. The cursor advances only when every item was written, so a failed pull is repeated in full, never skipped.

See [Connect your estate](/connect/).

Source: https://docs.atlanticagenticlabs.com/operations/runbooks/