Update Nexus error model to use Temporal failures by pdoerner · Pull Request #8799 · temporalio/temporal

pdoerner · 2025-12-11T17:07:16Z

What changed?

Many changes to support the Temporal SDK sending Temporal Failures instead of errors.

Depends on temporalio/api#682 and nexus-rpc/sdk-go#69

Why?

Consistency with other APIs and more rich information.

How did you test it?

built
covered by existing tests
added new unit test(s)
https://github.com/bergundy/nexus-error-compat-tests

bergundy

I don't think I will have time to fully review this before I go on PTO but the overall direction looks great.

When you plan on marking this ready for review, I would suggest adding the following tests:

Old server caller is compatible with a new server handler for start, cancel and callback requests
Encoded attributes returned from the SDK are passed through

bergundy

I took about a half hour reviewing this and I still don't think I caught everything. Before we can merge this we need:

Definitions and tests for what happens at each boundary for new and old components on either side.
End to end tests that cover the behavior with old SDKs.
End to end tests that cover the behavior with a new SDK after we have an implementation for the new paths.

bergundy · 2026-01-09T15:54:20Z

common/nexus/failure.go

+	}
+	apiFailure.FailureInfo = &failurepb.Failure_ApplicationFailureInfo{
+		ApplicationFailureInfo: &failurepb.ApplicationFailureInfo{
+			// Make up a type here, it's not part of the Nexus Failure spec.


We have NexusSDKFailureErrorFailureInfo in the API PR.

NexusSDKFailureErrorFailureInfo doesn't have a Details field. We only get to this point if we get an unexpected error type, so I thought it was better to capture the full information.

bergundy · 2026-01-09T15:58:50Z

common/nexus/failure.go

 }

-func OperationErrorToTemporalFailure(opErr *nexus.OperationError) (*failurepb.Failure, error) {
+func OperationErrorToTemporalFailure(opErr *nexus.OperationError, retryable bool) (*failurepb.Failure, error) {


You shouldn't need the retryable flag here, operation errors are non-retryable by definition and the resulting failure object should be a NexusOperationFailureInfo. This function doesn't seem necessary anymore, you should already have the original nexus failure on the operation error so all you need to do is convert to a temporal failure.

I also thought it would be unnecessary but I had some trouble removing it as this is the only place where we have the specific handling for CanceledFailureInfo.

common/nexus/nexusrpc/client.go

bergundy · 2026-01-09T16:38:38Z

common/nexus/nexusrpc/client.go

+	}
+	return &nexus.HandlerError{
+		Type:    errorType,
+		Message: response.Status,


This includes the HTTP status code, we need to trim that.

common/nexus/nexusrpc/server.go

bergundy · 2026-01-09T17:08:52Z

components/nexusoperations/executors.go

-					RetryBehavior: retryBehavior,
-				},
-			},
+		nf, err := nexus.DefaultFailureConverter().ErrorToFailure(handlerErr)


You should use the original failure here and then convert it to a temporal failure.

bergundy · 2026-01-09T17:11:04Z

components/nexusoperations/executors_test.go

 				require.Equal(t, enumsspb.NEXUS_OPERATION_STATE_BACKING_OFF, op.State())
 				require.NotNil(t, op.LastAttemptFailure.GetNexusHandlerFailureInfo())
-				require.Equal(t, "handler error (INTERNAL): internal server error", op.LastAttemptFailure.Message)
+				require.Equal(t, "internal server error", op.LastAttemptFailure.Message)


Please also check the handler error type in all of these tests.

bergundy · 2026-01-09T17:12:12Z

components/nexusoperations/frontend/handler.go

+		var failureErr *nexus.FailureError
+		var operationErr *nexus.OperationError
+		switch {
+		case errors.As(r.Error, &failureErr):


You should always get an operation error here.

bergundy · 2026-01-09T17:17:57Z

service/frontend/nexus_handler.go

 	switch t := response.GetOutcome().(type) {
+	case *matchingservice.DispatchNexusTaskResponse_Failure:
+		oc.metricsHandler = oc.metricsHandler.WithTags(metrics.OutcomeTag("handler_error:" + t.Failure.GetNexusHandlerFailureInfo().GetType()))
+		nf, err := commonnexus.APIFailureToNexusFailure(t.Failure)


You want to create a properly structured nexus failure here with metadata type set to nexus.HandlerError or nexus.OperationError and make sure the cause chain is populated correctly.

… SDK

**What changed?** Use Temporal failures for sending Nexus response errors. **Why?** Consistency with other Temporal APIs and compatibility with encryption proxies. **Breaking changes** Not explicitly, but server and SDK will need to be able to handle both error formats based on `capabilities` field. **Server PR** temporalio/temporal#8799 --------- Co-authored-by: Roey Berman <roey.berman@gmail.com>

bergundy · 2026-02-11T07:41:41Z

Closed in favor of #9290

pdoerner requested a review from bergundy December 11, 2025 17:07

bergundy reviewed Dec 11, 2025

View reviewed changes

pdoerner marked this pull request as ready for review December 17, 2025 18:10

pdoerner requested review from a team as code owners December 17, 2025 18:10

pdoerner requested review from gow and stephanos December 17, 2025 18:14

pdoerner requested a review from bergundy January 7, 2026 17:58

bergundy reviewed Jan 9, 2026

View reviewed changes

pdoerner and others added 8 commits January 23, 2026 11:19

Update Nexus error model to use Temporal failures

48c9392

Upgrade SDK dep to 1.38

bc39bbc

Set capabilities

e0ebac6

fix writeFailure

6a6ea6e

Bug fixes and test updates

273c5eb

lint

6dbbfed

Add handling for StartOperationResponse_Failure

781bc00

Upgrade api

699b0ff

bergundy force-pushed the nexus-error-model branch from 9a80fc7 to 699b0ff Compare January 23, 2026 19:55

bergundy added 12 commits January 23, 2026 13:48

Fix conversion from nexus failure to temporal failure

2c9cb58

Allow preserving more information for operation errors

7671e01

Fix retryable flag

c0eb657

Various edge cases and better handling of operation errors

d642560

Revert back to original error message

7d11cc8

Lint and some self-review

64da4df

Test fixes

d6e1b1f

Minor stuff

9083b1d

Merge branch 'main' into nexus-error-model

a5bec1e

Merge remote-tracking branch 'origin/main' into nexus-error-model

6a65c45

Bump API

53d941d

wip

4b11275

bergundy added 2 commits February 3, 2026 21:15

Fix tests and compat with generic Nexus

d76ef5a

Self review

033df6d

Quinn-With-Two-Ns mentioned this pull request Feb 5, 2026

💥 Use Temporal Failures for Nexus Error Serialization temporalio/sdk-java#2773

Draft

Inline the failure converter from the Nexus SDK and upgrade the Nexus…

f6b7aa8

… SDK

bergundy mentioned this pull request Feb 10, 2026

Use Temporal failures in Nexus APIs temporalio/api#682

Merged

bergundy added 6 commits February 10, 2026 21:41

Refactor

eaac970

Replace OperationCompletion with CompleteOperationOptions

ec8e7ae

Separate client instantiation and function invocation

1a0ce0a

Self review

1709d69

Merge remote-tracking branch 'origin/main' into nexus-error-model

1b58f0f

Bump Nexus SDK

f7a6fda

bergundy closed this Feb 11, 2026

bergundy deleted the nexus-error-model branch February 11, 2026 07:41

Conversation

pdoerner commented Dec 11, 2025 • edited by bergundy Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed?

Why?

How did you test it?

Uh oh!

bergundy left a comment

Choose a reason for hiding this comment

Uh oh!

bergundy 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

bergundy commented Feb 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

pdoerner commented Dec 11, 2025 •

edited by bergundy

Loading