Answers to common execution and recovery questions.

GetRatchet FAQ

Can GetRatchet run an agent for me? No. It records and manages an agent's tool calls. Your application runs the agent, and your worker runs registered durable handlers.

Does wrap() survive a process crash? No. It executes a local function in the current process. Durable enqueue() persists a named handler call for a separate worker to claim after a restart.

Are durable side effects exactly once? No. A lease can expire after a destination completed an action but before GetRatchet recorded success. Pass a stable idempotency key to the destination for payments, writes, and emails.

Why is my run still running after finishRun()? The finish request closes registration of new steps. The run waits for required queued, running, or retry-scheduled durable steps to settle.

Why is a job queued but unclaimed? Check an online worker, exact handler name and version, worker-key scope, project and environment, paused service, open circuit, and queue/database health. A newer handler version never silently replaces the queued version.

Can I replay a successful step or change its handler version? The current replay and recovery APIs accept exhausted or cancelled durable work only and preserve the exact saved handler version and input. A successful step is skipped. Publish a new contract and start new work for a new handler version.

What if an endpoint has no destination-side idempotency? Treat replay as potentially duplicating the side effect. Inspect destination records before approving it. A FORBIDDEN tool contract blocks GetRatchet replay.

Can I test a tool without changing customer data? Publish a SAFE contract backed by a safe test handler and call the synthetic test API. The SAFE classification is your assertion; test handlers must still avoid real side effects.

Who can approve AI recovery? An owner or admin must review the current dry-run plan and explicitly acknowledge duplicate risk. AI text never schedules work. External AI processing is off by default, and deterministic analysis works without a provider key.

What data goes to the optional AI provider? Only bounded, abstract statuses, outcome categories, durations, circuit state, and replay-safety classifications. No names, IDs, payloads, prompts, raw errors, or credentials are sent by default. See AI advisory.

When does old history disappear? Completed run details expire after the organization's selected 30–365 day retention period, 90 days by default. Cleanup runs in bounded batches during worker polls. Unfinished work is retained. Replay and idempotency lookup for a deleted run end with its removal.

Can I export my history? Admin-scoped run and audit exports are paginated and exclude payloads, raw errors, and secrets. Export before the retention sweep if you need older completed runs.

Where are my workers hosted? In your own long-lived process or container. Vercel hosts the GetRatchet API and console; it does not execute your registered tool code.

What happens if telemetry export is down? Traces and metrics may be lost, but export failures must not fail or block tool execution. Check collector configuration and retry the end-to-end trace verification when it recovers.

How can I restore a backup? Follow deployment and restore. Restore into an isolated non-production database first and verify the migration history and encrypted-data key before planning any production recovery.