resonate-basic-debugging-typescript

Resonate Debug and Troubleshoot

Overview

Use this skill to diagnose Resonate runtime issues in the TypeScript SDK or Resonate Server. Focus on reproducible symptoms, promise state, registration, determinism, and routing.

Triage Flow

1. Classify the failure: build/type error, runtime SDK error, server error code, or workflow stuck/hanging.
2. Confirm worker is running and connected to the correct server URL and group.
3. Inspect the promise state and call graph for the execution ID.
4. Validate registration names and serialization rules.
5. Check determinism and yield* usage inside durable functions.

CLI and Observability Tools

• Start a clean local server: resonate dev.
• Invoke a workflow: resonate invoke <promise-id> --func <name> --arg ....
• Inspect call graph: resonate tree <promise-id>.
• Inspect promise state: resonate promises get <id>.
• Search promises by state or tags: resonate promises search <id>.
• Resolve/reject external promises: resonate promises resolve|reject <id>.

Common Symptoms and Fixes

• Function not registered (1103): ensure register name matches invocation name.
• Function already registered (1102): avoid duplicate names or versions in one process.
• Args unencodeable (1106): pass only serializable args to RPC or top-level invocations.
• Promise already exists (40900): expected for idempotency; change the ID when you want a fresh run.
• Promise not found (40400): wrong ID or wrong server URL.
• Promise already resolved/rejected/timed out (40300-40303): treat as idempotency; pick a new ID or handle as cached result.
• Workflow hangs: target group mismatch, no active workers, or missing yield* before awaiting a future.
• Unexpected replays: expected after each checkpoint; avoid side effects outside ctx.run.

Code Examples

Minimal repro (worker)

// worker.ts
import { Resonate, type Context } from "@resonatehq/sdk";

const resonate = new Resonate({ url: "http://localhost:8001", group: "worker" });

function* ping(_: Context, name: string) {
  return `pong ${name}`;
}

resonate.register("ping", ping);