Resonate Basic Debugging — Java

Prerelease note. resonate-sdk-java is published on Maven Central — pin io.resonatehq:resonate-sdk-java:0.1.1. The API mirrors the Python SDK and may change before a stable 1.0. Requires Java 21+ — the SDK uses virtual threads, a feature generally available in Java 21. Every code block here is compile-verified against 0.1.1 with a Java 21 toolchain, and cross-checked against the resonatehq-examples/*-java repos and develop/java.mdx (docs PR #230).

Overview

Java's type system catches many bugs at compile time — typed method references and a typed ResonateHandle close off whole classes of error the dynamically-typed SDKs hit. The traps that remain are mostly at the durability boundary: untyped-handle decoding, CLI argument binding, replay double-fires, and the by-name-only constraints. This skill is a symptom-first guide to those failure modes.

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

Triage flow

1. Does it even build / start? Confirm a Java 21+ toolchain — the SDK uses virtual threads and will not run on Java 8/11/17.
2. Is the worker connected? Confirm the builder's url(...) (or RESONATE_URL) points at a running server, and r was built without throwing.
3. Is the function registered? By-name dispatch (rpc, the CLI) needs r.register(Owner::fn) on the executing group.
4. Is the promise stuck? Run resonate promise get <id> to check state (pending / resolved / rejected / timedout).
5. Is the workflow replaying but producing duplicates? An un-checkpointed side effect is re-running above a durable boundary.
6. Is a CLI-invoked function arity-mismatching? Each --arg binds to one positional parameter.
7. Is the worker up but not picking up work? r.stop() may have been called on a live worker.