# Recover a failed call

Find which layer owns the failure before changing your app. Keep the vendor in the World only if this workflow deliberately substitutes it.

## Start with the World and the request

From the application's directory, inspect status, diagnose routing, and read recent activity:

```console
$ npx volter world status
$ npx volter-world doctor <world-name> --root .
$ npx volter-world tail <world-name> --root . --no-follow
$ npx volter-world covers <world-name> --root . --repo .
```

These commands inspect your existing World; they are conditional diagnosis, not an empty-directory tutorial. Run the failing app command through `world run`. Use the twin URL reported by `world status` to read `GET /twin`: its identity, time rules and supported operations belong to that implementation. Do not paste credentials or raw real records into an issue.

| Symptom | Evidence to inspect | Next action |
|---|---|---|
| Call reached the real vendor, or an untwinned destination was refused | Selected vendors, `VOLTER_WORLD` inside the registered command, doctor and coverage | Run through the intended World; choose a twin for a needed vendor or deliberately exclude it. Never disable routing to hide the gap. |
| SDK rejects the credential before sending | Key parser, empty names in `.env.example`, twin credential manifest | Use the issued fake value or `fake-env` for a structurally valid throwaway key; never a real key. |
| Vendor-shaped unknown route / unsupported operation | `/twin`, the release's surface and unexercised operations | Narrow the workflow or ask the publisher to implement it. A success-shaped handler cannot repair a missing stored mutation. |
| Record absent, duplicate, or different from expected | SDK read, World log, branch and seed | Seed through the vendor API; reset only your disposable branch, then repeat. `up` resumes existing state. |
| Model answer/search result is a labeled stub | `/twin/scenario` matches and misses, handler file | Author a deterministic answer or lookup; verify calls and state, not prose quality. |
| Fault repeats or an SDK retry hides it | Handler order, `once`, SDK retry options, request log | Show the fault with retries disabled, then assert recovery with an explicit retry policy. Restart to rearm a once-handler. |
| Package pin mismatch | Installed package version and service source | Install the pinned version or trial/reconcile a candidate deliberately. Preserve retained state. |
| Browser cannot open the app or the callback never arrives | `app-url`, app readiness, endpoint registration, callback log | Boot the app as a World service; inspect the exact callback URL and verify signatures. |
| Process or native client bypasses routing | Client proxy and CA support; configured endpoint | Configure the client's supported proxy/CA or endpoint explicitly; [native routing](./route-a-cli-through-the-world.md) describes the limits. |
| Storage or startup failure | Doctor, lifecycle diagnostics, actual destination and ownership | Resolve the recorded cause; do not delete another actor's instance, worktree, cache or `node_modules`. |

## Report a reproducible problem

Keep the exact dependency versions, config, synthetic seed, handler and frozen clock together. Capture the app assertion and the minimal request shape, then [make a failure branch](./reproduce-a-failure.md). Name whether the issue belongs to the app, twin fidelity, scenario, routing or runtime. Report the catalog snapshot separately from the booted package; a recommendation is not proof of what ran.

The [coverage reference](../reference/coverage.md) distinguishes supported surface, exercised operations, browser assertions and unmeasured coverage. The [CLI reference](../reference/cli.md) owns command flags.