---
name: Go SDK
slug: temporal-go-sdk
type: github
source_url: https://github.com/temporalio/sdk-go
organization: Temporal
organization_slug: temporal
total_releases: 100
latest_version: v1.42.0
latest_date: 2026-04-08
last_updated: 2026-04-18
tracking_since: 2020-03-31
canonical: https://releases.sh/temporal/temporal-go-sdk
organization_url: https://releases.sh/temporal
---
The Go SDK shifted toward serverless and observability patterns while tightening compatibility constraints. The minimum Go version jumped to 1.24.0 in v1.42.0, and cross-namespace workflow operations were deprecated as the server disabled them by default. Worker heartbeating graduated as a core feature in v1.41.0, spawning a background nexus worker to stream metrics to the server—requiring server 1.29.1+ and dynamic config flags to fully activate. The SDK also introduced a Lambda worker module for running tasks in AWS Lambda on server invocation, and deprecated v1/v2 worker option versioning in favor of a simpler model. Bug fixes addressed replay crashes when codecs fail during session cancellation, heartbeat context propagation on shutdown, and test environment timeout enforcement.
Worker heartbeating graduated to default in v1.41.0, enabling periodic metrics reporting to the server through a background nexus worker per client namespace—requires Server 1.29.1+ and dynamic config flags to activate. v1.41.1 patched two critical issues: a permanent non-deterministic error on replay when Data Converters fail during session activity cancellation, and missing heartbeat context propagation during worker shutdown.
## Breaking Changes
### **💥** Minimum Go version updated to 1.24.0
The minimum Go version for the Go SDK has been updated 1.24.0 due to required dependency updates having this Go version.
### **💥** Namespace fields for cross-namespace workflow commands are deprecated
As of server 1.30.1, cross-namespace operations are disabled by default. The SDK has been updated to deprecate the corresponding fields and functions:
- `ChildWorkflowOptions.Namespace` field is deprecated
- `workflow.WithWorkflowNamespace` func is deprecated
## Highlights
### Serverless Lambda Workers (Pre-Release)
This release introduces a [module](https://github.com/temporalio/sdk-go/tree/master/contrib/aws/lambdaworker) which can be used together with upcoming changes to the Temporal server & cloud which allow you to run your worker in an AWS Lambda function which the server will invoke as-needed to process Workflow, Activity, and Nexus tasks - allowing you to do away with some of the operational burden of running a fleet of workers. Additional documentation on how to use this feature will be linked here when available.
### AWS S3 Storage Driver (Pre-Release)
This release introduces a [module](https://github.com/temporalio/sdk-go/tree/master/contrib/aws/s3driver) which can be used with [external storage](https://github.com/temporalio/sdk-go/blob/master/converter/extstore.go) to offload large payloads to S3 buckets in AWS instead of inlining them into workflow history. Additional documentation on how to use this feature will be linked here when available.
### Serialization Context for Codecs and Converters
This release introduces `SerializationContext` — an opt-in mechanism that provides metadata (e.g. namespace, workflow ID, activity type, etc...) to `DataConverter`, `PayloadCodec`, and `FailureConverter` implementations during serialization/deserialization.
## Bug Fixes
- Fix standalone activity header propagation so interceptors can access and modify headers.
## What's Changed
* Fix memory logger to share lock with derived loggers by @jmaeagle99 in https://github.com/temporalio/sdk-go/pull/2237
* Allow poller scale-down on timeout when server supports autoscaling by @Sushisource in https://github.com/temporalio/sdk-go/pull/2239
* Experimental: External Storage by @jmaeagle99 in https://github.com/temporalio/sdk-go/pull/2224
* No longer cancel pending polls on shutdown by @yuandrew in https://github.com/temporalio/sdk-go/pull/2199
* Report driver types through worker heartbeat by @jmaeagle99 in https://github.com/temporalio/sdk-go/pull/2246
* Delete some prominent but unimportant log messages by @dandavison in https://github.com/temporalio/sdk-go/pull/2247
* Fix test flakes by @yuandrew in https://github.com/temporalio/sdk-go/pull/2253
* Add Serialization context for codecs and converters by @yuandrew in https://github.com/temporalio/sdk-go/pull/2225
* Fix SAA header propagation by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/2256
* Experimental: AWS S3 storage driver by @jmaeagle99 in https://github.com/temporalio/sdk-go/pull/2257
* Serverless Lambda support by @Sushisource in https://github.com/temporalio/sdk-go/pull/2245
* Fix nonexistent version in lambda otel go mod by @Sushisource in https://github.com/temporalio/sdk-go/pull/2262
* Upgrade grpc to v1.79.3 by @yuandrew in https://github.com/temporalio/sdk-go/pull/2263
* Fix - provide default (empty) client config when default user config dir does not exist by @THardy98 in https://github.com/temporalio/sdk-go/pull/2266
* 💥 Update Temporal API to 1.62.7 by @jmaeagle99 in https://github.com/temporalio/sdk-go/pull/2267
* Update storage driver store context by @jmaeagle99 in https://github.com/temporalio/sdk-go/pull/2268
* Update version to 1.42.0 by @jmaeagle99 in https://github.com/temporalio/sdk-go/pull/2278
* Bump github.com/aws/aws-sdk-go-v2/service/s3 from 1.79.3 to 1.97.3 in /contrib/aws/s3driver/awssdkv2 by @dependabot[bot] in https://github.com/temporalio/sdk-go/pull/2276
## New Contributors
* @jmaeagle99 made their first contribution in https://github.com/temporalio/sdk-go/pull/2237
**Full Changelog**: https://github.com/temporalio/sdk-go/compare/v1.41.1...v1.42.0
# Bugfixes
Fixed a permanent NDE on replay when Data Converter or Codec fails on Session activity cancellation. Refer to https://github.com/temporalio/sdk-go/pull/2228 for more details.
Also fixed an issue with worker heartbeat ctx not being propagated for cancellation on worker shutdown. More details https://github.com/temporalio/sdk-go/pull/2215
## What's Changed
* Worker heartbeat ctx cancel fix by @yuandrew in https://github.com/temporalio/sdk-go/pull/2215
* separate out CI into more jobs, remove coverage upload by @yuandrew in https://github.com/temporalio/sdk-go/pull/2220
* Docs improvements by @yuandrew in https://github.com/temporalio/sdk-go/pull/2214
* Fix OnWorkflow mock to see propagated context headers by @kritibehl in https://github.com/temporalio/sdk-go/pull/2212
* Upgrade go.opentelemetry.io/otel/sdk to v1.40.0 by @yuandrew in https://github.com/temporalio/sdk-go/pull/2227
* Fix NDE due to task failure in sessions + cancellation by @Sushisource in https://github.com/temporalio/sdk-go/pull/2228
**Full Changelog**: https://github.com/temporalio/sdk-go/compare/v1.41.0...v1.41.1
# Breaking Changes
## **💥** Worker Heartbeats
This release adds a new feature called Worker Heartbeating. This feature spins up a single nexus-only worker per Client/Namespace in the background and periodically sends some basic metrics over to server for all of the workers registered on the same Client/Namespace.
Server version [1.29.1](https://github.com/temporalio/temporal/releases/tag/v1.29.1) and newer supports this feature. This feature will be enabled by default, although this currently requires a server dynamic config flag, --dynamic-config-value frontend.WorkerHeartbeatsEnabled=true to enable. Currently, the only way to interact with this new data is to also enable the flag --dynamic-config-value frontend.ListWorkersEnabled=true, then use CLI commands temporal worker list and temporal worker describe to query the data. If heartbeating is enabled with a server version older or with the config flag off, a single warning log Worker heartbeating configured for runtime, but server version does not support it. on worker startup will emit.
**💥** With the introduction of Worker Heartbeats, we’ve deprecated the `contrib/resourcetuner` lib, and instead created a new `contrib/sysinfo` lib. The resource tuner now lives in the `worker` package.
## **💥** Nexus Error Serialization Improvements
Note: Requires Temporal Server version 1.31.0 or later.
This release of the Go SDK includes a number of enhancements to error serialization for synchronous operations.
- `nexus.HandlerError` can now include its own message (and stack trace if the language supports it) independent from the `cause`
- `nexus.OperationError` can now include its own message (and stack trace if the language supports it) independent from the `cause`
- **💥** `nexus.OperationError` is now included in the error chain when a synchronous operation handler returns a `nexus.OperationError` . The `nexus.OperationError` will be translated to an appropriate Temporal error based on the state of the error. Previously this error was not included in the error chain.
- `OperationStateFailed` will be translated to an `ApplicationError`
- `OperationStateCancelled` will be translated to an `CanceledError`
These changes only effect synchronous operations. There is no change to errors for asynchronous operations like starting a workflow.
# Highlights
## Nexus Operation Timeouts
Note: Requires Temporal Server version 1.31.0 or later.
This release of the Go SDK adds more timeout options on `NexusOperationOptions` to control how long the caller wants to wait on different stages of the operation.
### Schedule-to-Start timeout
The 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 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,
})
```
## Add trampolining API for versioned continue-as-new
Added support for workflows to detect when their target deployment version
has changed and opt into upgrading via continue-as-new. New APIs:
- WorkflowInfo.GetTargetWorkflowDeploymentVersionChanged() — check if the
workflow's target version changed
- WorkflowInfo.GetContinueAsNewSuggestedReasons() — get reasons why CAN is
suggested
- ContinueAsNewVersioningBehaviorAutoUpgrade option for ContinueAsNewError
— explicitly upgrade to the new version on CAN
This enables a "trampolining" pattern: a pinned workflow detects a version
change, then continues-as-new with auto-upgrade to seamlessly move to the
latest deployment version. Both detection and action are fully opt-in,
avoiding accidental infinite CAN loops.
## What's Changed
* Nexus caller timeouts by @bergundy in https://github.com/temporalio/sdk-go/pull/2146
* Fix cgroup detection condition by @yuandrew in https://github.com/temporalio/sdk-go/pull/2179
* Introduce SDK flag to use user DC on Memo's by @yuandrew in https://github.com/temporalio/sdk-go/pull/2121
* 💥Add worker heartbeat support by @yuandrew in https://github.com/temporalio/sdk-go/pull/2186
* workflowcheck: Fix Go 1.26 false positives for SetFinalizer and godebug.Setting by @cretz in https://github.com/temporalio/sdk-go/pull/2192
* Bump github.com/sirupsen/logrus from 1.9.0 to 1.9.1 in /contrib/sysinfo by @dependabot[bot] in https://github.com/temporalio/sdk-go/pull/2194
* Change ShutdownWorker err log from Debug to Warn by @yuandrew in https://github.com/temporalio/sdk-go/pull/2195
* Make search attribute type more lenient when parsing by @cretz in https://github.com/temporalio/sdk-go/pull/2197
* Reduce test flakes by @yuandrew in https://github.com/temporalio/sdk-go/pull/2196
* Selector Signal fix with multiple workers by @yuandrew in https://github.com/temporalio/sdk-go/pull/2134
* Handle disabled TLS in envconfig ToClientOptions by @dandavison in https://github.com/temporalio/sdk-go/pull/2205
* Fix canceling external workflows that are children in testsuite by @yuandrew in https://github.com/temporalio/sdk-go/pull/1968
* Fix standalone activity result long-poll bug by @dandavison in https://github.com/temporalio/sdk-go/pull/2198
* 💥 Use Temporal Failures for Nexus Error Serialization by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/2181
* Fix 2090 child workflow goroutine leak by @kritibehl in https://github.com/temporalio/sdk-go/pull/2200
* Add trampolining API for versioned continue-as-new by @THardy98 in https://github.com/temporalio/sdk-go/pull/2216
* Upgrade go.opentelemetry.io/otel/sdk to v1.40.0 by @yuandrew in https://github.com/temporalio/sdk-go/pull/2218
* Revert "Upgrade go.opentelemetry.io/otel/sdk to v1.40.0" by @yuandrew in https://github.com/temporalio/sdk-go/pull/2221
## New Contributors
* @kritibehl made their first contribution in https://github.com/temporalio/sdk-go/pull/2200
**Full Changelog**: https://github.com/temporalio/sdk-go/compare/v1.40.0...v1.41.0
# Breaking Changes
Due to Standalone Activities, `testActivityToken` are used to keep track of activities, instead of just activityID, they now contain activityID and runID. Most users should not be affected, only if you're manually constructing task tokens in your tests.
# Highlights
Versioning v1 and v2 worker options and versioning intent have been marked as deprecated.
# Bug fixes
## Various test fixes and improvements
Properly set RootWorkflowExecution in child workflow env when testing.
Enforcement of heartbeat and start-to-close timeouts in test environment, as well as properly cancel timer when AwaitWithTimeout condition resolves.
## What's Changed
* Additional fields in env config by @stephanos in https://github.com/temporalio/sdk-go/pull/2145
* Enforce heartbeat and start-to-close timeouts in test environment by @mfateev in https://github.com/temporalio/sdk-go/pull/2144
* Upgrade Datadog tracer to dd-trace-go v2 by @yarinzirlin in https://github.com/temporalio/sdk-go/pull/2113
* Add release notes for contrib/datadog v0.5.0 by @yuandrew in https://github.com/temporalio/sdk-go/pull/2168
* Cancel timer when AwaitWithTimeout condition resolves by @mfateev in https://github.com/temporalio/sdk-go/pull/2153
* fix: set RootWorkflowExecution in child workflow env when testing by @pbrowne011 in https://github.com/temporalio/sdk-go/pull/2170
* Fix TestMockCallWrapperNotBefore test flake by @yuandrew in https://github.com/temporalio/sdk-go/pull/2173
* Enhance SDK flags so flags are off by default when first introduced by @yuandrew in https://github.com/temporalio/sdk-go/pull/2164
* Deprecate v1 and v2 versioning worker options and versioning intent by @carlydf in https://github.com/temporalio/sdk-go/pull/2174
* 💥 Standalone activities support by @maciejdudko in https://github.com/temporalio/sdk-go/pull/2158
* Switch from docker-compose to samples-server repo by @yuandrew in https://github.com/temporalio/sdk-go/pull/2183
* Remove experimental warning for worker deployment versioning and envconfig by @THardy98 in https://github.com/temporalio/sdk-go/pull/2176
* bump API to v1.62.1 by @yuandrew in https://github.com/temporalio/sdk-go/pull/2187
## New Contributors
* @yarinzirlin made their first contribution in https://github.com/temporalio/sdk-go/pull/2113
* @pbrowne011 made their first contribution in https://github.com/temporalio/sdk-go/pull/2170
**Full Changelog**: https://github.com/temporalio/sdk-go/compare/v1.39.0...v1.40.0
# Breaking Changes
It is now assumed that TLS is enabled if API key is provided. A new `TLSDisabled` ConnectionOption must be specified to explicitly disable TLS when an API key is provided.
# Highlights
## Plugin support
Plugins are a new way of providing easy configuration of workers and clients
# What's Changed
* chore: doc update improving non-determinism explanation by @sateeshkumarb in https://github.com/temporalio/sdk-go/pull/2117
* Add temporalnexus.WorkflowHandle.typeMarker by @bergundy in https://github.com/temporalio/sdk-go/pull/2116
* Deprecate `PreviousVersion` in Versioning responses by @ShahabT in https://github.com/temporalio/sdk-go/pull/2119
* Defer updating workflow completion metrics until completion accepted by server by @cretz in https://github.com/temporalio/sdk-go/pull/2112
* Upgrade api to 1.59.0 by @bergundy in https://github.com/temporalio/sdk-go/pull/2125
* upload nightly worker prom metrics to S3 by @THardy98 in https://github.com/temporalio/sdk-go/pull/2127
* 💥 [BREAKING] enable TLS if api key specified by @THardy98 in https://github.com/temporalio/sdk-go/pull/2126
* Add SpanFromWorkflowContext function for OTel by @jessefoster in https://github.com/temporalio/sdk-go/pull/2118
* Add resource_slots_cpu/mem_usage metrics by @yuandrew in https://github.com/temporalio/sdk-go/pull/2122
* Add summary to side effect and mutable side effect by @djeer in https://github.com/temporalio/sdk-go/pull/2129
* Bump logrus by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/2133
* Support Passing GRPC Header by attaching them to the Context by @chaptersix in https://github.com/temporalio/sdk-go/pull/2138
* expose default resource based slot suppliers by @kevinawoo in https://github.com/temporalio/sdk-go/pull/1922
* Add OnSideEffect and OnMutableSideEffect test mocks by @mfateev in https://github.com/temporalio/sdk-go/pull/2139
* Plugin support by @cretz in https://github.com/temporalio/sdk-go/pull/2135
## New Contributors
* @sateeshkumarb made their first contribution in https://github.com/temporalio/sdk-go/pull/2117
* @jessefoster made their first contribution in https://github.com/temporalio/sdk-go/pull/2118
* @djeer made their first contribution in https://github.com/temporalio/sdk-go/pull/2129
* @chaptersix made their first contribution in https://github.com/temporalio/sdk-go/pull/2138
* @kevinawoo made their first contribution in https://github.com/temporalio/sdk-go/pull/1922
**Full Changelog**: https://github.com/temporalio/sdk-go/compare/v1.38.0...v1.39.0
# Breaking Changes
When using sessions, deployment info is no longer sent on the worker specific task queue. This should reduce load on the server due to less temporary task queues. No changes in behaviour is expected for session workers.
# Bugfixes
Fixed a bug in Poller autoscaling causing `maxNumberOfPollers` to not be respected.
# What’s Changed
2025-10-09 - 2d05a73 - Use macOS 15 intel runners (#2072)
2025-10-13 - a117802 - Set worker version on eager start requests (#2075)
2025-10-13 - d61d5ef - Remove experimental warnings from worker tuners (#2077)
2025-10-14 - ad990a3 - Include failure details in query failure. Improved gRPC message too large detection. Fix flaky TestGrpcMessageTooLarge. (#2078)
2025-10-15 - 09e0634 - Upgrade to Nexus SDK 0.5.1 and inline the client implementation for tests (#2079)
2025-10-17 - f7eff2a - Remove Nexus deprecated APIs (#2081)
2025-10-22 - 8a24b22 - Add nightly throughput stress (#2087)
2025-10-24 - f34365e - Replace tctl references with Temporal CLI (#2080)
2025-10-27 - 2c43194 - Fix envconf docs path (#2093)
2025-10-29 - 5cd20cf - Set explicit permissions for GitHub Actions workflows (#2095)
2025-10-30 - 82be7bc - Cleanup nightly tps workflow (#2091)
2025-11-06 - 4b5d758 - Add actions-read permission to CI workflow (#2100)
2025-11-07 - a451bef - Remove experimental notes from poller behavior docs (#2096)
2025-11-12 - 9efde41 - fix: run maxNumberOfPollers poller routines instead of initialNumberOfPollers (#2105)
2025-11-14 - 7c0ebcf - OpenTelemetry: Specify span kind and don't set error type for benign exception (#2048)
2025-11-19 - 7025a6a - Stop sending deployment info for session per-worker task queue (#2088)
# Breaking Changes
## Versioning - Small API Rename
Renamed `BuildId` to `BuildID` in `WorkerDeploymentVersion` to match all other instances and Go naming convention.
# Bugfixes
## Reverting behavior for unblockSelectorSignal SDK flag
The previous fix introduced with the SDK flag `unblockSelectorSignal` was found to have a different bug with losing signals. For now the flag is getting turned off, and a more robust solution will be re-introduced in a future release. If anyone happens to rely on this new behavior already, the `UNBLOCK_SIGNAL_SELECTOR` env var can be set to enable the SDK flag.
# What’s Changed
2025-08-27 - b2d14779 - Disable some flaky tests (#2037)
2025-09-02 - a2ac97f6 - Changes to gRPC message too large error handling (#2042)
2025-09-12 - ef85feea - :boom: Rename BuildId -> BuildID in WorkerDeploymentVersion (#2051)
2025-09-19 - 96d9f2b6 - Activity reset (#2056)
2025-09-22 - 1528c324 - Add NexusInfo (#2054)
2025-09-23 - ff709e4e - Added retry policy to activity info (#2057)
2025-09-24 - aecdca8b - Fix CA cert config validation (#2052)
2025-10-02 - 8d431435 - populate ManagerIdentity from Describe (#2063)
2025-10-07 - 0968a50e - Pass AllowNoPollers flag to SetCurrentVersion and SetRampingVersion (#2067)
2025-10-07 - 3e46cbdf - Fix activity cancelation check (#2069)
2025-10-07 - 5ed31b6d - Revert setting unblockSelectorSignal SDK flag by default (#2070)
2025-10-07 - f88bdd39 - Implement SetWorkerDeploymentManagerIdentity (#2068)
## New Contributors
* @kaijchang made their first contribution in https://github.com/temporalio/sdk-go/pull/2052
**Full Changelog**: https://github.com/temporalio/sdk-go/compare/v1.36.0...v1.37.0
## Task Queue Fairness (Pre-release)
This release adds support for Task Queue Fairness. Fairness is a new feature of Temporal’s task queues that allows for more control over the order that tasks are dispatched from a backlog. It’s intended to address common situations like multi-tenant applications and reserved capacity bands. For more details see the go doc's on `temporal.Priority`.
Fairness is currently not supported in any OSS Temporal release, but support will be coming soon. To experiment with this feature please see the [pre-release development server](https://github.com/temporalio/cli/releases/tag/v1.4.1-cloud-v1-29-0-139-2.0) or if you are a Temporal Cloud customer reach out to your SA to be enabled once it is available in Temporal Cloud.
# Bugfixes
## No longer retry "gRPC message size to large" error
The SDK will no longer retry "gRPC message size to large" errors or related errors. These errors occur if the user tries to make a gRPC request that exceeds the Temporal Service limits (typically 4 MB).
# What’s Changed
2025-07-09 - 76f7c68 - Update test server to version 1.4.0 (#1994)
2025-07-09 - 7acd4d4 - Restore features branch to main (#1995)
2025-07-10 - 2ce5137 - Omit version token if empty (#1998)
2025-07-15 - 1dc8b10 - Fix data converter ToPayload error management (#2000)
2025-07-17 - 45621f4 - Remove experimental notice for UwS (#2004)
2025-07-21 - ce09baa - Add poller autoscaler (#1956)
2025-07-24 - 9ce618c - Accept search attributes for dev server (#2002)
2025-07-30 - f92dde1 - add compile time assertion (#2008)
2025-08-05 - 4026e02 - Move Nexus operation token generation outside of callback conditional (#2009)
2025-08-06 - 573d6de - Fix event type typo in Nexus cancellation types test (#2014)
2025-08-18 - f458e8a - Improve Nexus cancellation type test assertions (#2016)
2025-08-19 - 49ee963 - Upgraded go-grpc-middleware to v2.3.2 and x/tools to v0.36.0 (#2022)
2025-08-19 - 9ca81c6 - Add Fairness Keys/Weights (#2012)
2025-08-26 - 3080f44 - Add Go to Waitgroup (#2032)
2025-08-26 - 6d00d48 - Do not auto-retry gRPC-message-size-too-large errors (#2026)
# Breaking Changes
## Nexus - Deprecate API removed
Some Nexus APIs previously deprecated are now removed. Most notably `OperationID` was removed, users should switch to `OperationToken` .
# **Highlights**
### **Nexus Operation Cancellation Types (Pre-release)**
Users can now specify the cancellation type when cancelling a Nexus operations from a workflow. This allows for more granular control over how Nexus operations are cancelled, and how the caller is notified of the cancellation.
## Dynamic Workflow and Activities
Dynamic workflow and activities, which are nameless, can now be registered with `RegisterDynamicWorkflow` and `RegisterDynamicActivity`. This allows users to specify a default workflow to run if a worker does not recognize the workflow or activity being run on it.
## Workflow Metadata - Local Activity Summary
Local activities now support a `Summary` like normal activities and child workflows.
## Application Error Category
Application errors can specify a category, called `ApplicationErrorCategory`, to control logging and metrics behavior of activity failures
# What’s Changed
2025-04-18 - 0517ec9 - Make doc comment name match code name (#1920)
2025-04-21 - a921890 - Add support for root workflow execution to workflow info (#1923)
2025-04-23 - 50118c6 - Remove old Nexus workflow run operation token format (#1927)
2025-04-25 - ee78d25 - Add application err category (#1925)
2025-04-28 - 3db4820 - Add missing lock (#1938)
2025-04-29 - f3fcc94 - Update [[golang.org/x/net](http://golang.org/x/net)](http://golang.org/x/net) for CVE-2025-22872 (#1939)
2025-04-30 - 2c90009 - Fix trying to decode nil summary fields (#1941)
2025-04-30 - 4a43228 - Handle mix of RawValue and non-RawValue inputs for CompositeDataConverter (#1937)
2025-04-30 - 5a87f01 - Remove deprecated nexus APIs (#1944)
2025-04-30 - e2dfd9d - Add high level workflow describe (#1924)
2025-05-01 - 5de51a1 - Support for RequestIdReference in Link (#1877)
2025-05-02 - a10de39 - Encode the event type short string in the links (#1949)
2025-05-05 - 876aaaf - Remove per-file copyright headers (#1950)
2025-05-06 - 6d2cb6a - Implement Nexus operation cancellation types (#1917)
2025-05-07 - 52c7523 - Set Nexus links in the callback (#1945)
2025-05-08 - 46420c2 - Handle links from ExecuteWorkflow in Nexus WorkflowRunOperation (#1934)
2025-05-15 - b13a953 - Add SearchAttributes.Copy exception to workflowcheck (#1958)
2025-05-16 - f55d382 - Dynamic workflows and activities (#1946)
2025-05-27 - 71ce2dc - fix comments and grammar (#1959)
2025-05-28 - df05d05 - Mark Nexus operation cancellation type as Experimental. (#1960)
2025-05-30 - 22952b3 - Don't heartbeat local activity on non-graceful worker shutdown (#1933)
2025-06-03 - b955aa8 - Improve docs on NexusOperationCancellationTypeTryCancel (#1964)
2025-06-04 - 9de36a9 - Handle activity cancel due to worker shutdown properly (#1910)
2025-06-04 - a15c294 - :boom: [Breaking] Update versioning APIs to use struct (#1962)
2025-06-05 - f3b6fd4 - Use system time as started time (#1952)
2025-06-09 - 918fea8 - Fix missed spot w/ versioning string (#1969)
2025-06-10 - 28be770 - Deprecate versioning intents (#1970)
2025-06-10 - 2fb80f2 - Enable SDKFlagBlockedSelectorSignalReceive by default (#1762)
2025-06-17 - 46d0b10 - Stop Nexus worker. (#1974)
2025-06-18 - 4a4b322 - Deprecate more old versioning APIs (#1979)
2025-06-20 - 9682a69 - fix a typo (#1981)
2025-06-22 - a569259 - Clarify WithTags behaviour in metrics handler (#1975)
2025-06-25 - a1a14b9 - Fix GetWorkerStopChannel() for Local Activities (#1965)
2025-07-03 - 5be3364 - Plumb Summary through LocalActivityOptions (#1987)
2025-07-03 - f7174c2 - Fix TestActivityPause for Temporal Server v1.28.0 (#1989)
2025-07-04 - 8ee3a8a - Expose StartToCloseTimeout in ActivityInfo struct (#1990)
2025-07-07 - 4736849 - Release Go SDK v1.35.0
2025-07-07 - d68db26 - Apply context to data converter in update (#1991)
# **Highlights**
## Priority (Pre-release)
User can now set a priority key when scheduling a workflow, activity or child workflow. The priority key will be used to help prioritize certain tasks over others when there is a backlog. Priority is currently not supported in any OSS Temporal release, but support will be coming soon. To experiment with this feature please see the [pre-release development server](https://github.com/temporalio/cli/releases/tag/v1.3.1-priority.0) or if you are a Temporal Cloud customer reach out to your SA.
## Activity Pause (Pre-release)
The Go SDK now supports activity pause for heart beating activities. If an activity is paused while an attempt is running and the activity is heart-beating the activity context will be cancelled like the activity was cancelled.
# **Breaking Changes**
## Workflow Metadata Query
The built in `__temporal_workflow_metadata` will now use `RawValue` to encoded the query response. This should help with issues when a users data converter did not support `protobuf` payloads. The SDK's default data converter will already handle `RawValue`, but users custom data converter may need to be updated to handle `RawValue` correctly.
## What’s Changed
2025-02-26 - 9ce2508d - Remove WithStartOperation from docs (#1850)
2025-02-27 - 884681f7 - Add assertions for labels on Nexus metrics and logs (#1855)
2025-03-12 - 53719701 - Unblock using conflict policy UseExisting for Nexus WorkflowRunOperation (#1858)
2025-03-13 - 9f876e3d - Replace `github.com/pborman/uuid` with `github.com/google/uuid` (#1854)
2025-03-13 - efa70b9d - Add WorkflowExecutionAlreadyStarted error type to description (#1866)
2025-03-14 - 2dcb1b9a - Fix possibly failing to reserve slots due to stale issued number (#1870)
2025-03-14 - 54571a2b - Fix broken docstring (#1871)
2025-03-14 - 76cebd85 - Better Nexus error message (#1863)
2025-03-17 - 08d04be5 - Doc: Add blank lines before "Optional", "default", and "note" lines for clarity (#1873)
2025-03-17 - 695e7201 - Point to WorkflowExecutionErrorWhenAlreadyStarted in WorkflowIDReusePolicy/ConflictPolicy docstrings (#1872)
2025-03-20 - 07a817f1 - Add summary to Nexus operation (#1878)
2025-03-25 - 61cafbd6 - Allow local activities to finish running when stopping a worker (#1875)
2025-03-26 - 132f3568 - Extract BuilID from Version (#1881)
2025-03-26 - a80e6d54 - Add note that NewPayloadCodecGRPCClientInterceptor comes before NewFailureGRPCClientInterceptor (#1888)
2025-03-27 - 4b15a0c7 - Add RawValue support (#1879)
2025-03-27 - 9cd4d236 - Add FIPs to CI (#1892)
2025-03-28 - 31c4c308 - Disable some know flaky tests (#1893)
2025-03-28 - 9f5a4419 - Make sure schedule Update treats CatchupWindow properly (#1896)
2025-03-28 - ceab52ce - Fix `WorkflowId` being wrongly capitalized on example comments (#1891)
2025-03-31 - 0c9f60d3 - Add warning about anonymous functions as local activities (#1897)
2025-03-31 - 84f74820 - Update documentation for `Next` history iterator (#1853)
2025-04-01 - 4c897cd0 - Support environment configuration (#1849)
2025-04-02 - 5d5b2ff7 - Use RawValue for built-in query responses (#1894)
2025-04-02 - 9ba19ac6 - Make sure GetSystemInfo uses client timeout (#1900)
2025-04-03 - b9afba98 - Add Task Queue Priority (#1902)
2025-04-07 - 729bc240 - Add worker shutdown cause to context (#1904)
2025-04-09 - 797e9aa5 - Clarify ReusePolicy and ConflictPolicy doc comments (#1907)
2025-04-10 - 0ead7f5a - [doclink] Fix interface parsing (#1909)
2025-04-14 - 5940638f - Add support for activity pause (#1903)
2025-04-14 - a507124b - Update golang.org/x/net (#1913)
2025-04-14 - bba43df6 - don't try to call nil functions for TestUpdateCallback (#1914)
# **Highlights**
## Nexus
Attaching multiple Nexus callers to an underlying handler Workflow is now available in Pre-release.
## What’s Changed
2025-04-02 - e6f4d224 - Unblock using conflict policy UseExisting for Nexus WorkflowRunOperation (#1858)
# **Breaking Changes**
## Nexus
- ⚠️ **IMPORTANT** ⚠️ This SDK release requires server `>=1.27.0` to properly support the full set of changes from the previous SDK release. Most notably the built-in error translation logic changed in a way that may cause Nexus tasks to retry until the caller specified schedule-to-close timeout on certain failures, see more below.
- Setting `WorkflowIDConflictPolicy` to `WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING` has been temporarily disabled, and will fail requests with a retryable internal error.
- This is to protect users from making a false assumption that the same workflow can be used to back multiple operations. This capability will be enabled in a follow up release.
- Error translation logic changed in the following ways:
- `serviceerrors` returned by the client with `codes.AlreadyExists, codes.FailedPrecondition, codes.OutOfRange` now get translated to non retryable internal Nexus handler errors.
- Non retryable `ApplicationErrors` get translated to non retryable internal Nexus handler errors instead of bad request errors.
- `QueryRejectedError` and `WorkflowExecutionError` no longer get translated to a bad request automatically.
- Removed operation and service labels from Nexus schedule to start metric.
## **Versioning / Safe Deploy**
This release introduces a preview of new APIs that gracefully manage code changes and worker pools that support them. The goal is to better control which workers should execute new, and existing, workflows and activities tasks, based on their code and configuration.
A Worker Deployment is a collection of Worker Deployment Versions, typically associated with a single application. Each Version abstracts away the multiple Task Queues associated with this application, providing a common interface to set versioning policy to the workers polling those queues for tasks. A Worker Deployment has a Current Version, where tasks for new workflows and activities, and also tasks for `AutoUpgrade` existing workflows, are dispatched. A Worker Deployment can also have a Ramping Version to gradually move tasks from the Current Version to another one.
`AutoUpgrade` and `Pinned` are two Versioning Behaviors that can be specified when registering a workflow type. `Pinned` workflows are typically short lived, and are never affected by new versions, i.e., they do not need to use the patch API for compatibility. `AutoUpgrade` workflows are mostly long running, but they need to use patching to safely transition to new versions. The choice of `Pinned` vs `AutoUpgrade` ultimately depends on your willingness to keep old worker fleets running vs the complexity of patching.
In cases when you need to override the existing Versioning Behavior for a workflow, or a set of workflows, you can use the new `UpdateWorkflowExecutionOptions` API, which also operates on batches.
The following **EXPERIMENTAL** Versioning APIs implement Worker Deployments and Workflow Versioning Behavior annotations. It requires a server with version v1.27.0 or later.
- `Client.WorkerDeploymentClient()`:
- `Delete()`: Remove a Worker Deployment.
- `GetHandle()`: Return a handle to a Worker Deployment.
- `List()`: Enumerate Worker Deployments in the client's namespace
- `Client.WorkerDeploymentHandle()`:
- `SetCurrentVersion()`: Set the Current Version for a Worker Deployment.
- `SetRampingVersion()`: Set the Ramping Version for a Worker Deployment.
- `Describe()`: Return a description of this Worker Deployment.
- `DescribeVersion()`: Return a description of a Version in this Worker Deployment.
- `DeleteVersion()`: Remove a Version in this Worker Deployment.
- `UpdateVersionMetadata()`: Change user-provided metadata associated with a Version.
- `UpdateWorkflowExecutionOptions`: Override options of a workflow execution.
- `Worker.Options.DeploymentOptions`: Set Deployment Version and Workflow Behavior defaults.
- `Workflow.RegisterOptions.VersioningBehavior`: Annotate Workflow Behavior.
Documentation is coming soon. Do not use above APIs in production.
## Cloud Operator API
Removed the Cloud Operations Client from this SDK. Users should use https://github.com/temporalio/cloud-sdk-go instead.
# **Highlights**
## Nexus
🎉 Nexus is now generally available 🎉
- Added **experimental** support for Nexus operation interceptors.
- Added **experimental** tracing interceptor support for tracing calls from a workflow to a Nexus handler through client operations, such as starting a workflow.
- The test environment behavior is now more consistent with the server behavior, especially with changes made since the 1.25 release.
- Main Nexus APIs are no longer marked as experimental.
- The Nexus APIs and fields were marked as deprecated and will be removed in the next minor release:
- `OperationID` was renamed to `OperationToken` and the content of it was changed to a structured token instead of copying the workflow ID directly.
- `temporalnexus.NewSyncOperation` is now deprecated, use `nexus.NewSyncOperation` in combination with `temporalnexus.GetClient` to get similar functionality.
- Nexus now supports full error rehydration from the handler back to the caller workflow including support for the SDK’s `FailureConverter`.
- Upgraded Nexus SDK from `0.1.0` to `0.3.0`, see changes here:
- https://github.com/nexus-rpc/sdk-go/releases/tag/v0.2.0
- https://github.com/nexus-rpc/sdk-go/releases/tag/v0.3.0
## Workflow Reset
This release fixes a long standing [issue](https://github.com/temporalio/sdk-go/issues/723) in the Go SDK where workflows reset with a completed child workflow with the default WorkflowID would fail to replay due to a non-determinism error.
Note: This change will cause workflows that were previously stuck by https://github.com/temporalio/sdk-go/issues/723 to become unstuck.
## What’s Changed
2025-01-16 - 1c6e01b0 - Disable TestPinnedBehaviorThreeWorkers() test (#1780)
2025-01-17 - 2bf36d67 - Expose user metadata fields on scheduling workflows (#1782)
2025-01-17 - 454a8a8a - Add Nexus SignalWorkflowOperation (#1770)
2025-01-21 - 3befe6b9 - Upgrade api to 1.43.2 and Nexus to 0.1.1 (#1784)
2025-01-22 - b43588c5 - Fix update docstring to include context (#1785)
2025-01-23 - d2f4c141 - Update bug issue template to use `bug` label (#1787)
2025-01-24 - 34bbbbf0 - Clarify warning log on activity deadlone (#1786)
2025-01-25 - 751fa9a5 - Remove protolegacy build tag and InvalidUTF8Suite (#1789)
2025-01-28 - 7728bd7b - Unpin CLI (#1794)
2025-01-28 - c0ac0086 - Expose workflow client from Activity (#1783)
2025-01-31 - 02622974 - Enable speculative workflow task with commands (#1724)
2025-02-03 - 349283d8 - Fix Update-with-Start grpc deadline (#1798)
2025-02-03 - 8f05d019 - Don't replay commands from non-completed task (#1750)
2025-02-03 - bfd12ac9 - Fail Nexus Operation for incompatible input type (#1800)
2025-02-04 - 2030f9b9 - Revert WorkflowSignalOperation (#1801)
2025-02-04 - 24542f75 - Set Temporal-Namespace header on every namespace-specific gRPC request (#1467)
2025-02-06 - 6e75f6d1 - Expand arguments in UpdateWorkflow call when args equal one (#1799)
2025-02-07 - 150b4bd6 - Reserve __temporal_ prefix (#1806)
2025-02-07 - b8bc1c5e - Fix missing variadic ellipsis, added test to validate (#1804)
2025-02-08 - b9ad14a1 - Add option to override UI port (#1793)
2025-02-10 - 1540ba41 - Fix doc links on pkg.go.dev (#1795)
2025-02-10 - 22ebdc0d - Upgrade to Nexus SDK 0.2.0 (#1802)
2025-02-10 - e5ce2c4a - Replace `golang.org/x/exp` with stdlib (#1807)
2025-02-11 - 9d4a99aa - Add note that SetOnActivityHeartbeatListener may be called concurrently (#1818)
2025-02-11 - f29a8c5c - Rename operationID to token in TestWorkflowEnvironment (#1813)
2025-02-12 - 8101b82b - Remove Experimental annotation on Nexus APIs (#1816)
2025-02-13 - 82c56a91 - Only fallback to workflow ID as operation token when needed (#1821)
2025-02-13 - e5bc2980 - Stop checking for definitions inside of functions (#1819)
2025-02-14 - 4fb50dc4 - Properly convert Nexus HandlerErrors in the test env (#1822)
2025-02-14 - b19fc667 - Catchup tasks for Nexus features in the test env (#1824)
2025-02-14 - f2233597 - temporarily disable TestNumPollersCounter while I look into why it's flaking (#1826)
2025-02-18 - 617de7ee - Add tests for nexus error rehydration (#1767)
2025-02-18 - 623baddb - Remove cloud ops client (#1831)
2025-02-18 - 8f38795a - Remove operation and service labels from Nexus schedule to start metric (#1830)
2025-02-19 - 7e3d821e - Fix child WF ID generation (#1803)
2025-02-19 - e44e74e8 - Move SetStickyWorkflowCacheSize to global config setup (#1836)
2025-02-20 - c99ec473 - Translate relevant errors to non retryable internal Nexus handler errors (#1833)
2025-02-21 - 1720257a - More user-friendly NDE error message (#1837)
2025-02-21 - f5882aa4 - Support Worker Deployments 3.1 (#1832)
2025-02-22 - d32c252d - Nexus interceptors (#1841)
2025-02-24 - 2449502a - Support conflict options for starting Nexus operations in test framework (#1828)
2025-02-24 - 61c10ce5 - Fix AsTime() for nil proto timestamp (#1847)
2025-02-24 - b2b75c9b - [Nexus] Set OnConflictOptions for WorkflowRunOperation (#1797)
2025-02-25 - 24db5679 - Release Go SDK v1.33.0
2025-02-25 - ab1c3561 - Block using conflict policy UseExisting for Nexus WorkflowRunOperation (#1845)
2025-02-25 - f3da1f5b - Add Nexus tracing interceptor (#1844)
## Versioning / Safe Deploy (pre-release)
This release introduces a preview of new APIs that gracefully manage code changes and worker pools that support them. The goal is to better control which workers should execute new, and existing, workflows and activities tasks, based on their code and configuration.
Worker Deployments provide a consistent interface to set versioning policy for multiple Task Queues within a versioned application. Versioning Behaviors eliminate the need of patching short-running Workflows by pinning them to a particular version. The new `UpdateWorkflowExecutionOptions` API overrides versioning attributes for a particular workflow, or, using a batch command, for a set of workflows.
The following **EXPERIMENTAL** Versioning APIs implement Worker Deployments and Workflow Versioning Behavior annotations. It requires a server with version v1.26.2 or later.
* `Client.DeploymentClient()`:
- `Describe()`: Show properties of a Worker Deployment.
- `GetReachability()`: Return information to safely decommission Workers.
- `List()`: Enumerate Worker Deployments in the client's namespace
- `SetCurrent()`: Set the current Deployment for a Deployment Series.
- `GetCurrent()`: Find the current Deployment for a Deployment Series.
* `UpdateWorkflowExecutionOptions`: Override options of a workflow execution.
* `Worker.Options.DeploymentOptions`: Set Deployment and Workflow Behavior defaults.
* `Workflow.RegisterOptions.VersioningBehavior`: Annotate Workflow Behavior
Documentation is coming soon. Do not use above APIs in production.
## Workflow Update
Workflow Update, excluding Update-with-Start, is no longer marked as experimental.
## What’s Changed
2024-12-12 - ccb28ef5 - Versioning 3 (#1744)
2024-12-20 - 380add92 - Add Nexus links tests (#1613)
2025-01-08 - 423a9a3b - Remove Nexus OpCanceledBeforeStarted test (#1763)
2025-01-08 - 4dd46b82 - Resolve workflow name alias in Nexus WorkflowRunOperation (#1766)
2025-01-08 - 938dcadc - Fix versioning override with AutoUpgrade behavior (#1765)
2025-01-10 - 815c648b - small docs/rendering fixes (#1769)
2025-01-10 - a708f7e4 - Remove docker flag that disables versioning tests (#1771)
2025-01-10 - b8f9b44b - docs: fix bullets in intellisense (#1768)
2025-01-14 - 3506cd24 - Fix doclink tool's duplicate docstring generation issue (#1773)
## New Contributors
* @GSmithApps made their first contribution in https://github.com/temporalio/sdk-go/pull/1768
**Full Changelog**: https://github.com/temporalio/sdk-go/compare/v1.31.0...v1.32.1
### Nexus Breaking Changes
Add support for full Temporal error rehydration to provide a more consistent experience for Temporal users and on par debugging experience with workflows and activities..
Any Temporal errors returned over the Nexus boundary will now automatically be fully rehydrated on the caller side.
Some notable points:
- The Nexus SDK was upgraded to `v0.1.0`, which is a breaking change. Temporal Nexus users should refer to the [release notes](https://github.com/nexus-rpc/sdk-go/releases/tag/v0.1.0) before upgrading the Temporal SDK.
- `nexus.HandlerError` now has a `Failure` representation and is visible to the caller workflow.
- Arbitrary errors are translated to `ApplicationError` as they do in the rest of the Temporal SDK.
- `WorkflowExecutionError`, `QueryRejectedError`, and non retryable `ApplicationError`s are no longer translated to bad request handler errors, instead they're translated to `OperationError`s.
### Update With Start
`UpdateWithStartWorkflow` issues an update-with-start request. A `WorkflowIDConflictPolicy` must be set in the options. If the specified workflow execution is not running, then a new workflow execution is started and the update is sent in the first workflow task. Alternatively if the specified workflow execution is running then, if the `WorkflowIDConflictPolicy` is `USE_EXISTING`, the update is issued against the specified workflow, and if the `WorkflowIDConflictPolicy` is `FAIL`, an error is returned. The call will block until the update has reached the `WaitForStage` in the options. Note that this means that the call will notreturn successfully until the update has been delivered to a worker.
**Changes in this release**:
Instead of using the `ExecuteWorkflow` client method, update-with-start is invoked via a new client method `UpdateWithStartWorkflow`.
To use this method, you should first use `NewWithStartWorkflowOperation` to define the start-workflow operation. A workflow ID conflict policy is required. Then call `UpdateWithStartWorkflow`, passing it an `UpdateWithStartWorkflowOptions` containing your `WithStartWorkflowOperation`, together with an `UpdateWorkflowOptions` defining the update operation. This will return an `UpdateHandle`. The `WithStartWorkflowOperation` exposes a blocking `.Get(ctx)` method to obtain the workflow run targeted by the update.
## New Contributors
* @ReyOrtiz made their first contribution in https://github.com/temporalio/sdk-go/pull/1743
## What's Changed
2024-12-02 - 2c6bc1da - Introduce separate slot supplier for session activities (#1736)
2024-12-03 - 9c4dde85 - Use constant case in Nexus link URL eventType query param (#1741)
2024-12-03 - aa4535df - WorkflowTestSuite.UpdateWorkflow generate an update ID if none (#1738)
2024-12-05 - 01b52a21 - Tweak UpdateWorfklow docs (#1745)
2024-12-05 - 9d59447f - New Update-With-Start API (#1731)
2024-12-06 - 1f35a5ba - mock: in order mock calls using new testify mock.InOrder() method (#1743)
2024-12-06 - 7828e06c - Update Godoc for internal structs/funcs to clarify the package they are exposed under (#1735)
2024-12-09 - 41e9b33d - Tweak Update-with-Start error reporting (#1746)
2024-12-10 - 1b210845 - Bump SDKVersion to 1.31.0 (#1753)
2024-12-10 - d21ede2f - Nexus error rehydration (#1751)
**Full Changelog**: https://github.com/temporalio/sdk-go/compare/v1.30.1...v1.31.0
## Breaking Changes
Nexus async Operations backed by `ExecuteUntypedWorkflow` (i.e. `NewWorkflowRunOperation` and `NewWorkflowRunOperationWithOptions`) are now required to set the workflow ID on the `StartWorkflowOptions` parameter. If workflow ID is unset, the new error `ErrMissingWorkflowID` will be returned.
## What's Changed
* Update mac intel runner to macos-13 by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1702
* Fix lost signal from Selector when Default path blocks by @yuandrew in https://github.com/temporalio/sdk-go/pull/1682
* Support user metadata on activities and child/scheduled workflows by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1719
* Added SpanFromWorkflowContext function by @cdimitroulas in https://github.com/temporalio/sdk-go/pull/1711
* Improve Update Workflow testing UX by @yuandrew in https://github.com/temporalio/sdk-go/pull/1721
* Dedup duplicate update IDs for test environment by @yuandrew in https://github.com/temporalio/sdk-go/pull/1695
* When evicting workflows from cache make sure all go routines are evicted serially by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1718
* Add accessors for ChildWorkflowExecutionError fields by @yuandrew in https://github.com/temporalio/sdk-go/pull/1726
* Fix worker leak in eager dispatcher by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1723
* Set Nexus operation ID on callback headers by @pdoerner in https://github.com/temporalio/sdk-go/pull/1710
## New Contributors
* @cdimitroulas made their first contribution in https://github.com/temporalio/sdk-go/pull/1711
**Full Changelog**: https://github.com/temporalio/sdk-go/compare/v1.30.0...v1.30.1
# Highlights
## Nexus
We have made some improvements in Nexus metrics, `nexus_task_execution_failed` is now tagged with a `failure_reason` to help users understand the cause of the task failure.
see also: https://docs.temporal.io/references/sdk-metrics#nexus_task_execution_failed
## Test Environment
Improved support for mocking Nexus operations so you won’t need to have access to the operation itself or implementing a dummy operation. You can mock by calling `OnNexusOperation` and, when appropriate, `RegisterNexusAsyncOperationCompletion`.
Docs coming soon.
## Worker shutdown
When a Go SDK worker s shutting down it will now communicate to the Temporal service through a new `ShutdownWorker` API that the worker is no longer taking more tasks. If the Temporal service supports this feature all sticky workflow tasks will be assigned back to the normal task queue. This should reduce latency caused by shutting down a worker due to stick task queue timeout.
## What's Changed
2024-09-17 - 03e0341 - Use stable CLI for tests (#1637)
2024-09-17 - 8283604 - Remove DISABLE_NEXUS_TESTS env var from test code (#1640)
2024-09-23 - d10e871 - Update workflowcheck and allow it to handle aliased context (#1642)
2024-09-24 - cf3153e - expose ScheduleDescription (#1649)
2024-10-01 - 974ccc0 - Call the ShutdownWorker API as part of workflow worker cleanup (#1645)
2024-10-01 - f0ac2ee - Fix Nexus test env to respect ScheduleToCloseTimeout (#1636)
2024-10-02 - 772bc83 - MultiOperation retries non-durable Update (#1652)
2024-10-03 - 4e8380c - Error for unused Update operation (#1655)
2024-10-03 - cdd3070 - Remove history truncation (#1656)
2024-10-03 - d7a2128 - Enforce nexus request timeout in workflow test suite (#1653)
2024-10-03 - ea60ad5 - Evict the workflow from cache if their is a panic in the SDK (#1654)
2024-10-04 - 7d57a66 - ensure WorkflowTaskExecutionFailureCounter is called with a tag (#1658)
2024-10-08 - 75bd94b - Panic if endpoint or service is empty in NewNexusClient (#1661)
2024-10-08 - b300e50 - Nexus: Fix link not being attached to a workflow started via a Handler function (#1659)
2024-10-08 - b4e934e - Include updateID and updateName in update logger (#1660)
2024-10-08 - c82a8ac - Error if history contains unexpected events after the StartedEventId (#1662)
2024-10-09 - 3671c99 - fix link (#1665)
2024-10-14 - e503995 - Fix nexus_task_execution_failed to include OperationError outcome in start requests (#1664)
2024-10-15 - 7432064 - Add regression test to validate temporal_workflow_task_execution_failed on replay (#1669)
2024-10-16 - 959f581 - Read cgroups for resource tuner limits (#1632)
2024-10-16 - cfc38de - Fix TestNonDeterminismFailureCauseReplay integration test (#1674)
2024-10-18 - 1a13bf3 - Add Nexus `failure_reason` metric tag (#1671)
2024-10-24 - 5505d04 - Fix failure_reason label for nexus_task_execution_failed metric on task timeout (#1684)
2024-10-24 - 56b601d - Bump Nexus sdk-go to v0.0.11 (#1685)
2024-10-25 - 2bd372c - Upgrade API to v1.40.0 (#1688)
2024-10-25 - c0a1b59 - Translate gRPC Canceled code to Nexus HandlerErrorTypeInternal (#1680)
2024-10-28 - 37d1775 - Support for mocking nexus operations (#1666)
2024-10-28 - 4afb587 - Update-with-Start incompatible options (#1690)
## What's Changed
* Fix Version test failure due to 1.25.0 server release by @yuandrew in https://github.com/temporalio/sdk-go/pull/1629
* Update internal timers to use NewTimerWithOptions by @yuandrew in https://github.com/temporalio/sdk-go/pull/1618
* Nexus handler error translation by @bergundy in https://github.com/temporalio/sdk-go/pull/1626
**Full Changelog**: https://github.com/temporalio/sdk-go/compare/v1.29.0...v1.29.1
# Highlights
## Workflow Update-With-Start (Private Preview)
Note: This feature requires a server version 1.24+ and must be enabled. For self hosted you can set `frontend.enableExecuteMultiOperation` for Temporal Cloud please reach out to your Temporal account team or [Temporal Support Team](https://docs.temporal.io/cloud/support#support-ticket) to enable update with start in your namespace.
This release add support for Workflow Update-With-Start. Update-With-Start allows users to send a Workflow Update request along with a Start Workflow request in the same RPC. Users can think of Update-With-Start as analogous to Signal-With-Start except for Updates instead of Signals. To create a Update with start request users call `client.NewUpdateWithStartWorkflowOperation` and pass it to `WorkflowOptions.WithStartOperation` .
## Slot auto tuning (Private Preview)
* Added `WorkerOptions.Tuner` which is a `WorkerTuner` composed of `SlotSupplier` s. These interfaces can be used to customize how the worker decides to make slots available for Workflow and Activity Tasks. Some default slot suppliers are included:
* `ResourceBasedSlotSupplier` can be used to tune the workers slot count based on available memory and cpu resources. Make a ready-to-go `WorkerTuner` by using `NewResourceBasedTuner`. You can set a memory/cpu target and the worker will automatically try to reach those target usage levels.
* `FixedSizeSlotSupplier` always hands out slots until an upper bound
* `CompositeTuner` can be used to combine different kinds of `SlotSuppliers` to implement `WorkerTuner`.
Please give the resource based tuning a try and let us know how it works for you (feedback on community slack is welcome)! It'll work best if the worker is the only thing on your host using significant resources. Try setting the thresholds to a reasonable value like 0.8
Note: Resource based tuning and custom Slot Supplier implementations are currently considered experimental.
## User Metadata (Public Preview)
Note: This feature requires a server version 1.25+
This release add support for user metadata inside Workflows. This lets users set custom metadata on Workflow executions and certain APIs inside workflow that will be visible on the UI
Currently the Go SDK support:
- Fixed "summary" and "details" on workflow start
- Details on timer names through `workflow.NewTimerWithOptions`
- Details on signals, updates and query handlers through `workflow.SignalChannelOptions,` `workflow.QueryHandlerOptions` and `workflow.UpdateHandlerOptions`
See also: https://github.com/temporalio/features/issues/486
## What's Changed
2024-07-23 - 9c40461 - Add utility to get metrics handler for a Nexus operation (#1559)
2024-07-25 - bcc623d - Add support for managing schedule search attributes when when updating a schedule (#1562)
2024-07-26 - 1f0296c - Support for WorkflowIdConflictPolicy (#1563)
2024-07-29 - 2baa60e - Test duplicate rejected updates (#1569)
2024-07-29 - 6bb8f99 - Add rule code to warning (#1572)
2024-07-29 - dd28ced - Protect against legacy queries when state is destroyed (#1568)
2024-08-05 - 9b9201f - Use correct branch when not a pull request (#1578)
2024-08-05 - c5b519e - Build omes worker image w/ pending changes (#1577)
2024-08-06 - a1d05a6 - WorkerTuner & Resource based autotuning (#1546)
2024-08-06 - c2ce2e6 - Do not warn on unfinished handlers if workflow failed (#1581)
2024-08-08 - 2927574 - Switch omes to post-merge (#1583)
2024-08-09 - 0b7928d - Fix UpsertTypedSearchAttributes docs typo (#1585)
2024-08-14 - bb42a8b - Fix Go SDK CI (#1590)
2024-08-14 - c3ac511 - Improve docs and tests for HandlerUnfinishedPolicy (#1589)
2024-08-15 - 2a02c48 - Removing wording saying a signal will ignore start delay (#1592)
2024-08-15 - b5db2b7 - Add TaskQueueStats to DescribeTaskQueueEnhanced (#1553)
2024-08-20 - edc3c6c - Allow workflow interceptors to add nexus headers (#1604)
2024-08-21 - 1fe6141 - Support updates in tracing interceptor (#1595)
2024-08-21 - a31f86d - Address flaky tests (#1607)
2024-08-22 - 9bcc1a9 - Minor docstring grammar updates in activity.go (#1608)
2024-08-23 - 94f2100 - Minor correction to TQ stats docs (#1606)
2024-08-28 - 5364a47 - Handle Nexus links (#1605)
2024-08-29 - e85a098 - Update-with-Start operation (#1579)
2024-08-30 - 1b6220d - Mark Nexus link converter functions as experimental (#1615)
2024-08-30 - f47e644 - Experimental user metadata and workflow metadata query support (#1597)
2024-09-03 - 2af8c72 - Narrow scope of used slots lock for tracking slot supplier (#1617)
2024-09-03 - 52ea97f - Mark NewTimerWithOptions as Experimental (#1619)
2024-09-03 - eb41d13 - Expose QueryRejectedError (#1616)
2024-07-23 - 9c40461 - Add utility to get metrics handler for a Nexus operation (#1559)
2024-07-25 - bcc623d - Add support for managing schedule search attributes when when updating a schedule (#1562)
2024-07-26 - 1f0296c - Support for WorkflowIdConflictPolicy (#1563)
2024-07-29 - 2baa60e - Test duplicate rejected updates (#1569)
2024-07-29 - 6bb8f99 - Add rule code to warning (#1572)
2024-07-29 - dd28ced - Protect against legacy queries when state is destroyed (#1568)
2024-08-05 - 9b9201f - Use correct branch when not a pull request (#1578)
2024-08-05 - c5b519e - Build omes worker image w/ pending changes (#1577)
2024-08-06 - a1d05a6 - WorkerTuner & Resource based autotuning (#1546)
2024-08-06 - c2ce2e6 - Do not warn on unfinished handlers if workflow failed (#1581)
2024-08-08 - 2927574 - Switch omes to post-merge (#1583)
2024-08-09 - 0b7928d - Fix UpsertTypedSearchAttributes docs typo (#1585)
2024-08-14 - bb42a8b - Fix Go SDK CI (#1590)
2024-08-14 - c3ac511 - Improve docs and tests for HandlerUnfinishedPolicy (#1589)
2024-08-15 - 2a02c48 - Removing wording saying a signal will ignore start delay (#1592)
2024-08-15 - b5db2b7 - Add TaskQueueStats to DescribeTaskQueueEnhanced (#1553)
2024-08-20 - edc3c6c - Allow workflow interceptors to add nexus headers (#1604)
2024-08-21 - 1fe6141 - Support updates in tracing interceptor (#1595)
2024-08-21 - a31f86d - Address flaky tests (#1607)
2024-08-22 - 9bcc1a9 - Minor docstring grammar updates in activity.go (#1608)
2024-08-23 - 94f2100 - Minor correction to TQ stats docs (#1606)
2024-08-28 - 5364a47 - Handle Nexus links (#1605)
2024-08-29 - e85a098 - Update-with-Start operation (#1579)
2024-08-30 - 1b6220d - Mark Nexus link converter functions as experimental (#1615)
2024-08-30 - f47e644 - Experimental user metadata and workflow metadata query support (#1597)
2024-09-03 - 2af8c72 - Narrow scope of used slots lock for tracking slot supplier (#1617)
2024-09-03 - 52ea97f - Mark NewTimerWithOptions as Experimental (#1619)
2024-09-03 - eb41d13 - Expose QueryRejectedError (#1616)
2024-09-05 - 6f8719a - Improve active task queue definition (#1621)
### Specific Changes
* Update SDK version by @bergundy in https://github.com/temporalio/sdk-go/pull/1558
# Nexus pre-release
**⚠️ EXPERIMENTAL - APIs may change in a future release ⚠️**
See [the proposal](https://github.com/temporalio/proposals/blob/b72c49b0c2278e916265b00a49638006f8fce469/nexus/sdk-go.md) for usage instructions.
Self hosted users can [try Nexus out](https://github.com/temporalio/temporal/blob/main/docs/architecture/nexus.md#trying-nexus-out) in single cluster deployments with server version `1.25.0-rc.0` - **not meant for production use**.
Temporal Cloud users may reach out and open a support ticket to request access to the pre-release.
To use Nexus with the `temporal` CLI dev server:
1. download CLI `0.14.0-nexus.0` to the current directory:
```
curl -sSf https://temporal.download/cli.sh | sh -s -- --version v0.14.0-nexus.0 --dir .
```
2. run the dev server with the required configs:
```
./temporal server start-dev --dynamic-config-value system.enableNexus=true --http-port 7243
```
# Warn on unfinished handlers
The SDK will now `WARN` by default if a workflow is completed by the SDK with unfinished update handlers. Users can use `workflow.AllHandlersFinished` to wait for all handlers to be finished or set `UnfinishedPolicy` in `UpdateHandlerOptions`.
# Add Workflow safe Mutex and Semaphore
This release includes new helper interfaces `workflow.Mutex` and `workflow.Semaphore` that are workflow safe versions of a mutex and semaphore. These interfaces are to help users synchronize sensitive business logic across multiple coroutines or update handlers.
## What's Changed
* Clean up docs for NextRetryDelay by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1522
* Update some docs around grpc Dial options by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1514
* Wrap GRPC::CANCELED and DEADLINE_EXCEEDED in an SDK Timeout exception… by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1524
* Use grpc context for GetSystemInfo. by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1528
* Add option to handle scream snake case enums. by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1529
* Add workflow safe Mutex and Semaphore by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1530
* Ensure our proxy helpers forward metadata by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1531
* Point feature repo back to main by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1532
* Warn on unhandled updates by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1533
* Experimental cloud operations client by @cretz in https://github.com/temporalio/sdk-go/pull/1462
* add Name method to ReceiveChannel and SendChannel interface by @bentveljanzx in https://github.com/temporalio/sdk-go/pull/1538
* Test AllHandlersFinished in update validator by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1540
* Fix some Deprecated go docs by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1542
* Fix bug in updateWorkflowByID by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1548
* Fix typed search attributes with SignalWithStartWorkflow by @Quinn-With-Two-Ns in https://github.com/temporalio/sdk-go/pull/1552
* Add support for query parameter when listing schedules by @justinp-tt in https://github.com/temporalio/sdk-go/pull/1556
* Nexus by @bergundy in https://github.com/temporalio/sdk-go/pull/1555