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, install its locked @volter/world and @volter/world-runtime dependencies before using their local binaries. Then inspect status, diagnose routing, and read recent activity:
$ ./node_modules/.bin/volter world status
$ ./node_modules/.bin/volter-world doctor <world-name> --root .
$ ./node_modules/.bin/volter-world tail <world-name> --root . --no-follow
$ ./node_modules/.bin/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. |
Recover an incomplete first boot
A package that fails to start can leave a partial boot record. Fix the reported package error
first and retain the startup output. up preserves state, so an incomplete record is not silently
replaced on retry. Run doctor, then complete teardown with the same runtime version that started
that instance:
$ ./node_modules/.bin/volter-world doctor <world-name> --root .
$ ./node_modules/.bin/volter-world down <world-name> --root .After teardown is confirmed, ./node_modules/.bin/volter world up resumes retained branch data.
It can retry a stopped partial boot whose recorded services belong to the declared configuration.
If teardown or boot-record validation is still refused, retain the instance and report its diagnosis
to the runtime maintainer; do not erase ownership files or edit its boot record to make resume pass.
Resuming compute does not complete an unfinished first seed. The original startup may have failed
before .volter/seed.ts ran, or the seed may have written only some records. A retry with an existing
instance preserves that data and does not automatically run the seed again.
Read the retained startup output and seed entry, then inspect the expected records through the
vendor's SDK inside world run. The World log alone does not prove that the seed completed:
seeded starting records are separate from the app's pending writes. If the seed never ran, run it
explicitly. If it wrote partial data, first make it reuse existing records and create only missing
ones through the vendor API, or complete those missing writes deliberately. Once repeating the
entry is safe:
$ ./node_modules/.bin/volter world seedRead the expected records back through the SDK before continuing the app. The seed and reset guide shows a seed that looks before creating. Do not reset retained history just to force the initial seed to run again.
Only for a new, disposable instance with no history or records to keep, retain its diagnostics and use
./node_modules/.bin/volter-world down <world-name> --root . --purge. Purge verifies teardown and
refuses referenced state. After purge, follow fresh setup rather than assuming discarded records will resume.
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.
For a twin defect, open the exact release in the catalog and use Report an issue when the publisher supplied that link, or the issue tracker in Source repository. For a CLI, catalog, website or documentation problem, open a public catalog issue. Name the component in the title so maintainers can route it. You do not need a paid Volter account to report a problem; GitHub requires its own account to submit an issue.
Include your operating system, Node version, exact CLI and twin versions, the command and its error, the selected catalog snapshot, and a small example using synthetic data. Describe the expected and observed result. Remove credentials, proxy environment values and real records. If you cannot tell which component failed, include the diagnosis you have rather than changing your app to hide the failure.
The coverage reference distinguishes supported surface, exercised operations, browser assertions and unmeasured coverage. The CLI reference owns command flags.