Volter World

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.

SymptomEvidence to inspectNext action
Call reached the real vendor, or an untwinned destination was refusedSelected vendors, VOLTER_WORLD inside the registered command, doctor and coverageRun 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 sendingKey parser, empty names in .env.example, twin credential manifestUse 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 operationsNarrow 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 expectedSDK read, World log, branch and seedSeed 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 fileAuthor a deterministic answer or lookup; verify calls and state, not prose quality.
Fault repeats or an SDK retry hides itHandler order, once, SDK retry options, request logShow the fault with retries disabled, then assert recovery with an explicit retry policy. Restart to rearm a once-handler.
Package pin mismatchInstalled package version and service sourceInstall the pinned version or trial/reconcile a candidate deliberately. Preserve retained state.
Browser cannot open the app or the callback never arrivesapp-url, app readiness, endpoint registration, callback logBoot the app as a World service; inspect the exact callback URL and verify signatures.
Process or native client bypasses routingClient proxy and CA support; configured endpointConfigure the client's supported proxy/CA or endpoint explicitly; native routing describes the limits.
Storage or startup failureDoctor, lifecycle diagnostics, actual destination and ownershipResolve 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 seed

Read 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.

View Markdown source

On this page