From ebd51b89d5cd0a87ea93d088fc2187b4654d3053 Mon Sep 17 00:00:00 2001 From: Quinn Klassen Date: Wed, 25 Feb 2026 16:23:57 -0800 Subject: [PATCH 1/3] Document new Nexus Operation timeouts --- docs/encyclopedia/nexus-operations.mdx | 53 +++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 2 deletions(-) diff --git a/docs/encyclopedia/nexus-operations.mdx b/docs/encyclopedia/nexus-operations.mdx index 4254432c3d..1397daf662 100644 --- a/docs/encyclopedia/nexus-operations.mdx +++ b/docs/encyclopedia/nexus-operations.mdx @@ -14,6 +14,10 @@ keywords: - nexus circuit breaking - nexus circuit breaker - circuit breaker is open + - nexus timeouts + - schedule-to-close timeout + - schedule-to-start timeout + - start-to-close timeout - execution semantics - temporal sdk - versioning @@ -179,7 +183,7 @@ For example, when you execute a Nexus Operation in a caller Workflow the followi ## Automatic retries {#automatic-retries} Once the caller Workflow schedules an Operation with the caller's Temporal Service, the caller's Nexus Machinery keeps trying to start the Operation. -If a [retryable Nexus error](/references/failures#nexus-errors) is returned the Nexus Machinery will retry until the Nexus Operation's Start-to-Close-Timeout is exceeded. +If a [retryable Nexus error](/references/failures#nexus-errors) is returned the Nexus Machinery will retry until the Nexus Operation's [Schedule-to-Close timeout](#schedule-to-close-timeout) is exceeded. For example, if a Nexus handler returns a [retryable error](/references/failures#nexus-errors), or an [upstream timeout](https://github.com/nexus-rpc/api/blob/main/SPEC.md#predefined-handler-errors) is encountered by the caller, the Nexus request will be retried up to the [default Retry Policy's](https://github.com/temporalio/temporal/blob/de7c8879e103be666a7b067cc1b247f0ac63c25c/components/nexusoperations/config.go#L111) max attempts and expiration interval. @@ -193,6 +197,51 @@ This differs from how Activities and Workflows handle errors and retries: See [errors in Nexus handlers](/nexus/error-handling#errors-in-nexus-handlers) to control the retry behavior by returning a [non-retryable Nexus error](/references/failures#non-retryable-nexus-errors). +## Timeouts {#timeouts} + +Nexus Operations support three types of timeouts that control how long the caller is willing to wait at different stages of the Operation lifecycle. +These timeouts are set by the caller when scheduling the Operation. + +### Schedule-to-Close timeout {#schedule-to-close-timeout} + +The Schedule-to-Close timeout limits the total duration from when the Operation is scheduled to when it completes. +This is the overall timeout for the entire Operation. +The Nexus Machinery [automatically retries](#automatic-retries) failed requests internally until this timeout is exceeded, at which point the Operation fails with a [NexusOperationTimedOut](/references/events#nexusoperationtimedout) event. + +For asynchronous Operations, this timeout covers the full lifecycle: scheduling, starting, and completing. +For synchronous Operations, this timeout covers the time from scheduling to receiving the result. + +In Temporal Cloud, the maximum Schedule-to-Close timeout is 60 days. + +### Schedule-to-Start timeout {#schedule-to-start-timeout} + +The Schedule-to-Start timeout limits how long the caller is willing to wait for the Operation to be started (or completed, if synchronous) by the handler. +If the Operation is not started within this timeout, it fails with `TIMEOUT_TYPE_SCHEDULE_TO_START`. + +If not set or set to zero, no Schedule-to-Start timeout is enforced. + +:::note + +The Schedule-to-Start timeout requires Temporal Server version 1.31.0 or later. + +::: + +### Start-to-Close timeout {#start-to-close-timeout} + +The Start-to-Close timeout limits how long the caller is willing to wait for an asynchronous Operation to complete after it has been started. +If the Operation does not complete within this timeout after starting, it fails with `TIMEOUT_TYPE_START_TO_CLOSE`. + +This timeout only applies to asynchronous Operations. +Synchronous Operations ignore this timeout because they complete as part of the start request. + +If not set or set to zero, no Start-to-Close timeout is enforced. + +:::note + +The Start-to-Close timeout requires Temporal Server version 1.31.0 or later. + +::: + ## Circuit breaking {#circuit-breaking} Circuit breaking handles deployment issues, such as remote service faults, that take time to recover. @@ -296,7 +345,7 @@ Pending Nexus Operations: 1 ### At-least-once execution semantics and idempotency -The Nexus Machinery provides reliable execution with at-least-once execution semantics for a Nexus Operation, until the caller's Schedule-to-Close-Timeout is exceeded, at which time the overall Nexus Operation times out. +The Nexus Machinery provides reliable execution with at-least-once execution semantics for a Nexus Operation, until the caller's [Schedule-to-Close timeout](#schedule-to-close-timeout) is exceeded, at which time the overall Nexus Operation times out. The Nexus Machinery breaks up the [Nexus Operation lifecycle](/nexus/operations#operation-lifecycle) into one or more [Nexus Tasks](/tasks#nexus-task) that a Nexus handler is responsible for processing. If a Nexus handler times out or returns a non-retryable Nexus error, then the Nexus Machinery will retry the Nexus request to provide at-least-once execution. From ccf951d96dd45f1db9f12e55ba8b4ffcd9a03899 Mon Sep 17 00:00:00 2001 From: Quinn Klassen Date: Tue, 3 Mar 2026 08:10:35 -0800 Subject: [PATCH 2/3] Respond to PR comments --- docs/develop/go/temporal-nexus.mdx | 39 ++++++++++++++++++++++++++ docs/encyclopedia/nexus-operations.mdx | 7 ++--- 2 files changed, 42 insertions(+), 4 deletions(-) diff --git a/docs/develop/go/temporal-nexus.mdx b/docs/develop/go/temporal-nexus.mdx index b388ea6602..1bb219ad7b 100644 --- a/docs/develop/go/temporal-nexus.mdx +++ b/docs/develop/go/temporal-nexus.mdx @@ -336,6 +336,45 @@ func HelloCallerWorkflow(ctx workflow.Context, name string, language service.Lan ``` +### Set Nexus Operation timeouts + +Nexus Operations support [three types of timeouts](/encyclopedia/nexus-operations#timeouts) that control how long the caller is willing to wait at different stages of the Operation lifecycle. +Set these timeouts in `NexusOperationOptions` when calling `ExecuteOperation`. + +#### Schedule-to-Close timeout + +The [Schedule-to-Close timeout](/encyclopedia/nexus-operations#schedule-to-close-timeout) limits the total duration of the Operation from when it is scheduled to when it completes. +The Nexus Machinery automatically retries failed requests until this timeout is exceeded. + +```go +fut := c.ExecuteOperation(ctx, service.HelloOperationName, service.HelloInput{Name: name, Language: language}, workflow.NexusOperationOptions{ + ScheduleToCloseTimeout: 10 * time.Minute, +}) +``` + +#### Schedule-to-Start timeout + +The [Schedule-to-Start timeout](/encyclopedia/nexus-operations#schedule-to-start-timeout) limits how long the caller will wait for the Operation to be started by the handler. +If not set, no Schedule-to-Start timeout is enforced. + +```go +fut := c.ExecuteOperation(ctx, service.HelloOperationName, service.HelloInput{Name: name, Language: language}, workflow.NexusOperationOptions{ + ScheduleToStartTimeout: 2 * time.Minute, +}) +``` + +#### Start-to-Close timeout + +The [Start-to-Close timeout](/encyclopedia/nexus-operations#start-to-close-timeout) limits how long the caller will wait for an asynchronous Operation to complete after it has been started. +This timeout only applies to asynchronous Operations. +If not set, no Start-to-Close timeout is enforced. + +```go +fut := c.ExecuteOperation(ctx, service.HelloOperationName, service.HelloInput{Name: name, Language: language}, workflow.NexusOperationOptions{ + StartToCloseTimeout: 5 * time.Minute, +}) +``` + ### Register the caller Workflow in a Worker After developing the caller Workflow, the next step is to register it with a Worker. diff --git a/docs/encyclopedia/nexus-operations.mdx b/docs/encyclopedia/nexus-operations.mdx index 1397daf662..a1db454b71 100644 --- a/docs/encyclopedia/nexus-operations.mdx +++ b/docs/encyclopedia/nexus-operations.mdx @@ -183,7 +183,7 @@ For example, when you execute a Nexus Operation in a caller Workflow the followi ## Automatic retries {#automatic-retries} Once the caller Workflow schedules an Operation with the caller's Temporal Service, the caller's Nexus Machinery keeps trying to start the Operation. -If a [retryable Nexus error](/references/failures#nexus-errors) is returned the Nexus Machinery will retry until the Nexus Operation's [Schedule-to-Close timeout](#schedule-to-close-timeout) is exceeded. +If a [retryable Nexus error](/references/failures#nexus-errors) is returned the Nexus Machinery will retry until the Nexus Operation's [Schedule-to-Close timeout](#schedule-to-close-timeout) or [Schedule-to-close timeout](#schedule-to-close-timeout) is exceeded. For example, if a Nexus handler returns a [retryable error](/references/failures#nexus-errors), or an [upstream timeout](https://github.com/nexus-rpc/api/blob/main/SPEC.md#predefined-handler-errors) is encountered by the caller, the Nexus request will be retried up to the [default Retry Policy's](https://github.com/temporalio/temporal/blob/de7c8879e103be666a7b067cc1b247f0ac63c25c/components/nexusoperations/config.go#L111) max attempts and expiration interval. @@ -208,10 +208,9 @@ The Schedule-to-Close timeout limits the total duration from when the Operation This is the overall timeout for the entire Operation. The Nexus Machinery [automatically retries](#automatic-retries) failed requests internally until this timeout is exceeded, at which point the Operation fails with a [NexusOperationTimedOut](/references/events#nexusoperationtimedout) event. -For asynchronous Operations, this timeout covers the full lifecycle: scheduling, starting, and completing. -For synchronous Operations, this timeout covers the time from scheduling to receiving the result. +This timeout covers the full [Nexus Operation lifecycle](https://docs.temporal.io/nexus/operations#operation-lifecycle). Asynchronous Operations are scheduled, started, and completed. Synchronous Operations don't have an intermediate started state because they complete as part of the start request. -In Temporal Cloud, the maximum Schedule-to-Close timeout is 60 days. +In Temporal Cloud, the [maximum Schedule-to-Close timeout is 60 days](https://docs.temporal.io/cloud/limits#nexus-operation-duration-limits). ### Schedule-to-Start timeout {#schedule-to-start-timeout} From 642c5ba51db1d264664ac1ad51e915036aae9ee9 Mon Sep 17 00:00:00 2001 From: Quinn Klassen Date: Tue, 3 Mar 2026 08:24:54 -0800 Subject: [PATCH 3/3] Fix links --- docs/develop/go/temporal-nexus.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/develop/go/temporal-nexus.mdx b/docs/develop/go/temporal-nexus.mdx index 1bb219ad7b..224edc44aa 100644 --- a/docs/develop/go/temporal-nexus.mdx +++ b/docs/develop/go/temporal-nexus.mdx @@ -338,12 +338,12 @@ func HelloCallerWorkflow(ctx workflow.Context, name string, language service.Lan ### Set Nexus Operation timeouts -Nexus Operations support [three types of timeouts](/encyclopedia/nexus-operations#timeouts) that control how long the caller is willing to wait at different stages of the Operation lifecycle. +Nexus Operations support [three types of timeouts](/nexus/operations#timeouts) that control how long the caller is willing to wait at different stages of the Operation lifecycle. Set these timeouts in `NexusOperationOptions` when calling `ExecuteOperation`. #### Schedule-to-Close timeout -The [Schedule-to-Close timeout](/encyclopedia/nexus-operations#schedule-to-close-timeout) limits the total duration of the Operation from when it is scheduled to when it completes. +The [Schedule-to-Close timeout](/nexus/operations#schedule-to-close-timeout) limits the total duration of the Operation from when it is scheduled to when it completes. The Nexus Machinery automatically retries failed requests until this timeout is exceeded. ```go @@ -354,7 +354,7 @@ fut := c.ExecuteOperation(ctx, service.HelloOperationName, service.HelloInput{Na #### Schedule-to-Start timeout -The [Schedule-to-Start timeout](/encyclopedia/nexus-operations#schedule-to-start-timeout) limits how long the caller will wait for the Operation to be started by the handler. +The [Schedule-to-Start timeout](/nexus/operations#schedule-to-start-timeout) limits how long the caller will wait for the Operation to be started by the handler. If not set, no Schedule-to-Start timeout is enforced. ```go @@ -365,7 +365,7 @@ fut := c.ExecuteOperation(ctx, service.HelloOperationName, service.HelloInput{Na #### Start-to-Close timeout -The [Start-to-Close timeout](/encyclopedia/nexus-operations#start-to-close-timeout) limits how long the caller will wait for an asynchronous Operation to complete after it has been started. +The [Start-to-Close timeout](/nexus/operations#start-to-close-timeout) limits how long the caller will wait for an asynchronous Operation to complete after it has been started. This timeout only applies to asynchronous Operations. If not set, no Start-to-Close timeout is enforced.