Resonate Basic Debugging Rust

Resonate Basic Debugging — Rust

SDK note. This SDK is in active development (v0.6.0, published on crates.io), and documented behaviors may shift between releases. Failure modes listed here are what the documented surface produces; new ones will appear as the SDK grows.

Overview

Rust's failure modes differ from TS's and Python's. Compile-time type errors catch many bugs the other SDKs only discover at runtime; the remaining runtime failures are usually serde, tokio, or registration-name related. This skill covers the shapes you'll actually see.

For the language-agnostic replay + recovery mental model, read durable-execution first.

Triage flow

1. Does it compile? If cargo build fails, you're in type-error territory (likely: missing Result<T> return, wrong first-parameter type, forgotten & on Context/Info, missing ? on an await)
2. Does it register? resonate.register(fn) returns a Result; unwrap it and look at the error (duplicate name, bad signature)
3. Does the function kind match expectations? The SDK infers kind from the first parameter — &Context vs &Info vs a value type
4. Is serde happy? Input/output types need Serialize + Deserialize derives; stack traces mentioning serde_json::Error mean a type doesn't derive correctly
5. Is the tokio runtime correct? #[tokio::main] or #[tokio::test(flavor = "multi_thread")] needed; single-threaded runtime can deadlock on SDK internals
6. Check server + SDK compatibility. The SDK version in Cargo.toml must align with the server version you're testing against; check the SDK CHANGELOG for compatibility notes

Install / dependency issues

Symptom: cannot find crate 'resonate' or version-resolution errors.

Cause: Check your Cargo.toml. The SDK is published on crates.io — pin the current release:

[dependencies]
resonate = { package = "resonate-sdk", version = "0.6" }
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }

For pre-release work that must track main directly (e.g. to pick up a not-yet-released fix):

resonate = { package = "resonate-sdk", git = "https://github.com/resonatehq/resonate-sdk-rs", branch = "main" }

Run cargo update -p resonate-sdk to pull the latest version when upstream changes.

Registration errors

Serde errors

Symptom: serde_json::Error { ... } at runtime when a function result crosses a checkpoint or RPC boundary.

Cause: Input or output type doesn't derive Serialize / Deserialize. Every argument and return value gets serialized by Resonate.

Fix:

use serde::{Serialize, Deserialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
struct Order {
    id: String,
    amount: f64,
}

#[resonate::function]
async fn process(ctx: &Context, order: Order) -> Result<Order> {
    // ...
    Ok(order)
}

Common sub-issues:

• #[serde(rename_all = "snake_case")] if your JSON payload conventions differ from Rust field names
• #[serde(skip_serializing_if = "Option::is_none")] for optional fields
• Enums need #[serde(tag = "type")] for internally-tagged representations; pick a representation and stick with it across all workers

ctx vs info confusion

Symptom: "Cannot find method run on &Info" at compile time.

Cause: Only &Context has run, rpc, sleep. &Info gives metadata but not execution capabilities.

Fix: use &Context as the first parameter when the function needs to orchestrate sub-tasks.

Missing ? on .await

Symptom: compile error about Result<String> doesn't implement something, or future cannot be awaited.

Cause: Every async method in the SDK returns a Future<Output = Result<T>>. Awaiting gives you Result<T>; you still need ? to extract T:

// Bad — `result` is Result<String>, not String
let result = ctx.run(leaf, "input".into()).await;

// Good
let result: String = ctx.run(leaf, "input".into()).await?;

.spawn() is synchronous — don't add .await after it

Symptom: compile error like "no method named poll found", a type-mismatch where the compiler expected DurableFuture<T> but got an opaque future type, or a lifetime/borrow error that only appears on the .spawn() line.

Cause: As of SDK 0.5.0+, ctx.run(...).spawn() / ctx.rpc(...).spawn() on a Context is synchronous — it returns the handle directly (ctx.run → Result<DurableFuture<T>>, ctx.rpc → Result<RemoteFuture<T>>), without suspending. Adding .await after .spawn() is an old habit that no longer compiles.

// BAD — .await after .spawn() fails to compile in 0.5.0+
let fut = ctx.run(leaf, "input".into()).spawn().await?;

// CORRECT — .spawn() is sync; unwrap with ? then await the DurableFuture later
let fut = ctx.run(leaf, "input".into()).spawn()?;

// ... do other work ...

// later: a single .await on the DurableFuture gets the actual T
let result: String = fut.await?;

This differs from TS/Python's begin_run / ctx.rfi, which return a promise-like handle from an async call. In Rust, you use ? (not .await?) to unwrap the Result<DurableFuture> from .spawn(), then a single .await? later to get T.

tokio runtime mismatches

Symptom: deadlock at startup, or "Cannot drop runtime in a runtime" panic.

Cause: wrong tokio runtime flavor, or nested Runtime::block_on inside an already-running runtime.

Fix: use #[tokio::main] on your entry point with the default multi-threaded runtime. Do NOT wrap Resonate calls in Handle::block_on inside a durable function.

#[tokio::main]
async fn main() -> Result<()> {
    let resonate = Resonate::local();
    resonate.register(my_fn).unwrap();

    let result: String = resonate.run("id", my_fn, "input".into()).await?;
    println!("{}", result);

    resonate.stop().await?;
    Ok(())
}

For tests, prefer #[tokio::test(flavor = "multi_thread")] over the default single-thread flavor when tests involve multiple workers.

Non-determinism regressions

Durable functions replay from the last checkpoint. Any non-deterministic code above a checkpoint can cause divergence.

Common Rust-specific footguns:

// BAD — system time changes between runs
#[resonate::function]
async fn bad(ctx: &Context) -> Result<()> {
    let now = std::time::SystemTime::now();
    if now > SOME_THRESHOLD {
        ctx.run(branch_a, "".into()).await?;
    } else {
        ctx.run(branch_b, "".into()).await?;
    }
    Ok(())
}

// BAD — random values change between runs
use rand::Rng;

#[resonate::function]
async fn bad2(ctx: &Context) -> Result<()> {
    let roll = rand::thread_rng().gen_range(0..100);
    // branch on roll — different on each replay
    Ok(())
}

The SDK does NOT expose ctx.time.time() / ctx.random.random() helpers. Until those land, the safe pattern is:

• Do non-deterministic work inside a leaf (so the value is checkpointed)
• Or derive branches from the invocation's stable ID / input args, not runtime randomness

#[resonate::function]
async fn good(ctx: &Context, input: String) -> Result<()> {
    // random work inside a checkpointed leaf
    let roll = ctx.run(roll_dice, ()).await?;
    if roll > 50 {
        ctx.run(branch_a, input).await?;
    } else {
        ctx.run(branch_b, input).await?;
    }
    Ok(())
}

#[resonate::function]
async fn roll_dice(_: ()) -> Result<u32> {
    Ok(rand::thread_rng().gen_range(0..100))
}

Minimal repro

// src/main.rs
use resonate::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    let resonate = Resonate::local();
    resonate.register(ping).unwrap();

    let result: String = resonate.run("ping:alice", ping, "Alice".into()).await?;
    println!("{}", result);

    resonate.stop().await?;
    Ok(())
}

#[resonate::function]
async fn ping(name: String) -> Result<String> {
    Ok(format!("pong {}", name))
}

If this fails, the problem is infrastructure (Cargo deps, tokio runtime, SDK version). If it succeeds but your real code fails, diff your function signatures against this template.

Server compatibility

The Rust SDK (v0.6.0) ships with tested compatibility against the Resonate server; check the SDK CHANGELOG for the minimum server version. Before reporting a bug, verify:

1. Your SDK version — cargo metadata | grep resonate for the resolved version
2. Your server version — resonate --version on the server binary
3. The SDK's compatibility notes — check the SDK's CHANGELOG or README on GitHub

Expect that the API surface may shift between 0.x releases until the SDK reaches 1.0.

CLI one-liners

resonate dev                                  # local dev server
resonate tree <invocation-id>                 # call-graph
resonate promises get <id>                    # single promise state
resonate promises search 'order:*'            # prefix search
resonate promises resolve <id> --data '{}'    # settle a pending promise

The CLI is SDK-agnostic; same commands work for TS, Python, Rust worker ecosystems.

Rust SDK API coverage status

Cross-reference with resonate-basic-durable-world-usage-rust for the full treatment; quick summary for debug triage:

Exists in v0.6.0 source (even if rust.mdx doesn't mention it)

• ctx.promise::<T>() — Context-side HITL primitive (source: resonate/src/context.rs:335)
• ctx.get_dependency::<T>() + Info::get_dependency::<T>() — type-dispatched DI (source: context.rs:120, info.rs:43)
• ctx.detached(func, args) — fire-and-forget remote execution (source: context.rs:405); .spawn()? returns a DetachedHandle, and handle.id().await? gives the durable promise ID
• ctx.info() returning extra accessors branch_id, tags
• resonate.with_dependency::<T>(value) — ephemeral-side DI builder

If a workflow is mysteriously missing one of these, the issue is likely docs staleness, not SDK absence. Cite source paths when an agent reviewer questions whether an API exists.

NOT in v0.6.0 source

• ctx.random.random() / ctx.time.time() — do non-det work inside a leaf so it's checkpointed
• ctx.panic() / ctx.assert() — use Rust's panic! / assert! (non-recoverable) or Result propagation (recoverable)

Each of these may land in a future version; check docs/develop/rust.mdx AND the resonate-sdk-rs source when a new release ships — iter-18/19 review showed docs can lag source meaningfully.

Related skills

• resonate-basic-ephemeral-world-usage-rust — Client APIs at the process-entry layer
• resonate-basic-durable-world-usage-rust — Context APIs inside durable functions
• durable-execution + resonate-philosophy — foundational; many debug sessions end up being about patterns warned against here
• resonate-basic-debugging-typescript + -python — sibling SDKs for comparison