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:
$ 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 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. 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 distinguishes supported surface, exercised operations, browser assertions and unmeasured coverage. The CLI reference owns command flags.