💥 Use Temporal Failures for Nexus Error Serialization by Quinn-With-Two-Ns · Pull Request #2773 · temporalio/sdk-java

Quinn-With-Two-Ns · 2026-02-05T22:21:57Z

💥 Use Temporal Failures for Nexus Error Serialization. The Java SDK now responds to Nexus operation failures and task failures with plain Temporal Failures. This change also allows OperationException and HandlerException to have their own message and stacktrace independent of their cause. If the Server does not support the new format the SDK converts back to the old format before sending the response.

Requires:

Note

Medium Risk
Touches Nexus error/failure serialization and server reply paths, which can affect cross-version interoperability and how failures are surfaced/attributed. Backward-compat fallback and expanded tests reduce risk but edge cases could still change failure shapes and metrics tags.

Overview
Switches Nexus task failure reporting to the new API format by sending plain Temporal Failure protos for both operation failures (StartOperationResponse.failure) and handler failures (RespondNexusTaskFailedRequest.failure), enabling independent message/stacktrace on OperationException/HandlerException.

Adds compatibility logic to downgrade to the old HandlerError/UnsuccessfulOperationError format when the server doesn’t advertise Request.Capabilities.temporal_failure_responses (or when forced via temporal.nexus.forceOldFailureFormat). Updates NexusUtil and DefaultFailureConverter to round-trip Temporal failures through Nexus metadata/details and preserve stack traces.

Test server and SDK tests are updated/expanded to handle both formats (including forced-old-format suites) and validate metrics tagging for failed vs canceled operations; CI bumps the Temporal CLI version and build config moves nexusVersion to 0.5.0-SNAPSHOT (plus mavenLocal() for resolution).

^{Written by Cursor Bugbot for commit 9545fd2. This will update automatically on new commits. Configure here.}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7b2a0c78ca

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

temporal-sdk/src/main/java/io/temporal/internal/worker/NexusWorker.java

build.gradle

cursor · 2026-02-05T22:46:08Z

temporal-sdk/src/main/java/io/temporal/internal/common/NexusUtil.java

    }
    return Failure.newBuilder()
-        .setMessage(failure.getMessage())
+        .setMessage(temporalFailure.getMessage())


Duplicated failure serialization logic in NexusUtil

Low Severity

temporalFailureToNexusFailure and temporalFailureToNexusFailureInfo share nearly identical logic for serializing a Temporal failure to JSON. Both call PROTO_JSON_PRINTER.print() with the same arguments, handle InvalidProtocolBufferException identically, and set the same metadata. Only the return type differs (Failure vs FailureInfo). The JSON serialization logic could be extracted to a shared helper.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 349588549b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

build.gradle

.github/workflows/ci.yml

temporal-sdk/src/main/java/io/temporal/internal/worker/NexusWorker.java

mjameswh · 2026-02-25T17:41:29Z

temporal-sdk/src/main/java/io/temporal/failure/DefaultFailureConverter.java

-          return new HandlerException(info.getType(), cause, retryBehavior);
+          if (failure
+              .getMessage()
+              .startsWith(String.format("handler error (%s)", info.getType()))) {


I understand this is here to allow proper decoding of legacy errors, but for which languages exactly? If we mean to support legacy errors coming from Go or others, are we sure the casing returned by .getType() here would match the error type of other SDKs?, or should we make this condition a little bit more resilient?

Any old failure serialized by Go or Java. This is the handler error type so that should match the Nexus spec and consistent across Go and Java

temporal-sdk/src/main/java/io/temporal/internal/worker/NexusWorker.java

mjameswh · 2026-02-25T18:50:59Z

temporal-sdk/src/main/java/io/temporal/internal/worker/NexusWorker.java

    }

+    @SuppressWarnings("deprecation")
    private void sendReply(


The structure of this function is very hard to reason about.

If we do this, are you still concerned about the structure?

That one is certainly the most patent culprit, but I'd also try to restructure this to avoid mixing happy paths and failure cases.

Like, instead of:

if (taskResponse != null) { if (!supportTemporalFailure && taskResponse.getStartOperation().hasFailure()) { // some failure case on old server reuturn } // happy path AND some failure case on newer servers } // other failure cases

I'd suggest restructuring the function along the line of:

if (taskResponse != null && !taskResponse.getStartOperation().hasFailure()) { // Operation succeeded } else if (taskResponse != null) { // Operation failed - OperationError } else if (response.getHandlerException()) { // Operation failed - HandlerError } else { // throw ... }

I'm not sure that will really be clearer since we use the same gRPC method to respond to the server ion the first and second case here.

I have an attempt to refactor to make it clearer let me push and we can discuss

temporal-sdk/src/main/java/io/temporal/internal/worker/NexusWorker.java

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

cursor · 2026-02-25T22:35:14Z

build.gradle


 allprojects {
    repositories {
+        mavenLocal()


SNAPSHOT dependency and mavenLocal not suitable for merge

Medium Severity

mavenLocal() was added to the allprojects repositories block alongside nexusVersion = '0.5.0-SNAPSHOT'. Both are development-time configurations — mavenLocal() can cause non-reproducible builds by resolving artifacts from the local cache, and SNAPSHOT dependencies are inherently unstable. These need to be replaced with a released version before merging.

Additional Locations (1)

build.gradle#L33-L34

VegetarianOrc

LGTM, just a couple of minor things

VegetarianOrc · 2026-02-27T23:18:52Z

temporal-sdk/src/main/java/io/temporal/internal/common/NexusUtil.java

    String details;
    try {
-      details = JSON_PRINTER.print(failure.toBuilder().setMessage("").build());
+      details = PROTO_JSON_PRINTER.print(temporalFailure.toBuilder().setMessage("").build());


In Go & Python, we're clearing the stack trace out of the details as well as the message. Seems like it'd make sense to do it here as well.

VegetarianOrc · 2026-02-27T23:31:53Z

temporal-sdk/src/main/java/io/temporal/internal/common/NexusUtil.java

+        HandlerError.newBuilder()
+            .setErrorType(e.getErrorType().toString())
+            .setRetryBehavior(mapRetryBehavior(e.getRetryBehavior()));
+    // TODO: check if this works on old server


Have we checked this? If so, let's remove this todo

Quinn-With-Two-Ns requested a review from a team as a code owner February 5, 2026 22:21

Quinn-With-Two-Ns marked this pull request as draft February 5, 2026 22:22

chatgpt-codex-connector bot reviewed Feb 5, 2026

View reviewed changes

temporal-sdk/src/main/java/io/temporal/internal/worker/NexusWorker.java Outdated Show resolved Hide resolved

cursor bot reviewed Feb 5, 2026

View reviewed changes

Quinn-With-Two-Ns added 6 commits February 18, 2026 16:12

Update proto

296f927

Update Nexus failure conversion

8607ddb

Update Nexus failure conversion

0dec89d

Update Nexus failure conversion

3b8fe5e

Add support to the time skipping test server

4219704

Bump test server version

3495885

Quinn-With-Two-Ns force-pushed the NEXUS-38 branch from d69b39f to 3495885 Compare February 19, 2026 00:18

Quinn-With-Two-Ns marked this pull request as ready for review February 19, 2026 00:27

chatgpt-codex-connector bot reviewed Feb 19, 2026

View reviewed changes

build.gradle Show resolved Hide resolved

.github/workflows/ci.yml Outdated Show resolved Hide resolved

Fix some CI failures

3d44cf5

cursor bot reviewed Feb 20, 2026

View reviewed changes

temporal-sdk/src/main/java/io/temporal/internal/worker/NexusWorker.java Outdated Show resolved Hide resolved

mjameswh reviewed Feb 25, 2026

View reviewed changes

temporal-sdk/src/main/java/io/temporal/internal/worker/NexusWorker.java Outdated Show resolved Hide resolved

mjameswh reviewed Feb 25, 2026

View reviewed changes

temporal-sdk/src/main/java/io/temporal/internal/worker/NexusWorker.java Outdated Show resolved Hide resolved

Respond to PR comments

9545fd2

Quinn-With-Two-Ns requested a review from mjameswh February 25, 2026 22:10

cursor bot reviewed Feb 25, 2026

View reviewed changes

mjameswh approved these changes Feb 26, 2026

View reviewed changes

VegetarianOrc reviewed Feb 28, 2026

View reviewed changes

Conversation

Quinn-With-Two-Ns commented Feb 5, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

cursor bot Feb 5, 2026

Choose a reason for hiding this comment

Duplicated failure serialization logic in NexusUtil

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 25, 2026

Choose a reason for hiding this comment

SNAPSHOT dependency and mavenLocal not suitable for merge

Uh oh!

VegetarianOrc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Quinn-With-Two-Ns commented Feb 5, 2026 •

edited by cursor bot

Loading