💥 Breaking Changes
WorkflowOutboundCallsInterceptorhas newsleep(Duration, TimerOptions)and
await(Duration, TimerOptions, String, Supplier)methods. Implementations that don't extend
WorkflowOutboundCallsInterceptorBaseneed to add them, and Base subclasses override them to see calls with options.- Experimental: A
@TemporalOperationhandler can now send only one signal per operation invocation;signal
andsignalWithStartcount toward the same limit. While the first signal is in flight, or after it succeeds, a
second signal to any workflow throws aBAD_REQUESTHandlerException. If the first signal fails, the handler can
signal again.signalWithStartfrom such a handler also requires an explicit workflow ID, since a defaulted ID
differs on each retried Nexus task and would start another workflow. - Workers now retryably fail a workflow or activity task whose payloads exceed the namespace's size
limit, instead of sending it to the server. Disable with
WorkerOptions.Builder.setDisablePayloadErrorLimit; tune warnings with the experimental
WorkflowServiceStubsOptions.Builder.setPayloadLimits.
Added
- Tracing options and
ContextPropagator.encodeHeaders()can opt into header processing using
the configured client's payload codec. Only opted-in producers' output is encoded, while
application-supplied wire-ready headers are unchanged. Receiving consumers use private decoded
views. Existing propagators default to false; custom converter wrappers can expose their codec
throughPayloadCodecProvider. - Poller pools now report their poller target to the server on each poll and in the worker
heartbeat, covering workflow, sticky workflow, activity, and Nexus pools. An autoscaling pool
reports its current target, a fixed-size pool its configured size. (We'll use this count on the
server side for now for load balancing pollers between workers, and for creating a per-worker
poller count metric.) - Applications can use the experimental
@TransferTypeConvertibleannotation and
TransferTypeConverterinterface to convert top-level model values to transfer types. The SDK
applies this conversion to workflow, activity, Nexus, and schedule payloads, including failure
details.WorkflowClient.getOptions().getDataConverter()returns the transfer-aware converter
that the client uses. - Worker heartbeats now report detected Graal native-image and Kotlin runtimes alongside the JVM
version. Detection is best effort and respects the worker environment information opt-out.
Factory registration overloads accept an implementation class for runtime detection, including
Spring Boot workflow registrations. - Added experimental
Copyable<T>for isolated in-process copies. Local activities copy
eligible inputs for each attempt and outputs for live execution, preserving history serialization
and replay. Deeply immutable values may return themselves. - Added experimental
ChildWorkflowOptions.Builder.setVersioningOverrideand
VersioningOverride.OneTimeVersioningOverridefor explicit pinned, auto-upgrade, and one-time
child workflow routing. Invalid child overrides are reported asInvalidVersioningOverrideFailure
underChildWorkflowFailure.
Child workflow overrides and one-time routing require Temporal Server 1.32.0 or later. - Added experimental client config extensions to
temporal-envconfig. Extensions implement
ClientConfigExtension, read their own config fromprofile.<profile>.ext.<name>TOML tables
(exposed asClientConfigProfile.getExt()) and env vars, and are passed via
LoadClientConfigProfileOptions.Builder.setExtensionsto contribute service stubs plugins to
ClientConfigProfile.toWorkflowServiceStubsOptions(). Strict mode does not reject keys under
ext. WorkerFactoryOptions.Builder.setLoggerTagPrefixthat can be used to customized structured logging tags (MDC keys)
set by Temporal SDK in worker context.- Spring Boot: the
workersattribute of@WorkflowImpl,@ActivityImpland@NexusServiceImplnow resolves property
placeholders such as${my.worker.name}, astaskQueuesalready does. Workflow.sleep(Duration, TimerOptions)andWorkflow.await(Duration, TimerOptions, Supplier)let workflows set a
summary on the timer behind a sleep or a timed await, likeWorkflow.newTimer(Duration, TimerOptions)already does.- Add nonblocking
Async.awaitoverloads whose promises complete when a workflow condition becomes true or a timeout expires. - Workflow tasks taking longer than 5 seconds now log a
[TMPRL1104]warning reporting the task duration and the
external storage downloads and uploads that contributed to it. The threshold is configurable with the
TEMPORAL_WORKFLOW_TASK_DURATION_WARN_SECONDSenvironment variable. - Nexus operation handlers now forward inbound callback links to the workflows and signals they start, instead of
dropping them. - Nexus handlers now propagate
NexusSerializationContextto the workflows, workflow updates, and
standalone activities they start. These use it only for their results and failures, which are
returned to the Nexus caller. Standalone activities also use it for their heartbeat details, which
the server includes in their timeout failures.
To complete such an activity asynchronously, read the context from
ActivityInfo.getNexusSerializationContext(), store it with the task token, and pass it to
ActivityCompletionClient.withContext(NexusSerializationContext). - Experimental:
ActivityClientandScheduleClientnow support external storage when configured with
ActivityClientOptions.Builder.setExternalStorageorScheduleClientOptions.Builder.setExternalStorage. - Experimental:
StorageDriverStoreContextandStorageDriverSelectContextnow havegetNamespace(), returning
the namespace of the client or worker performing the store.
Changed
- Experimental: The S3 storage driver now writes payloads stored without a workflow or activity target under
v0/ns/{namespace}/d/sha256/{hash}, using the namespace of the storing client or worker (nullwhen it is
unknown), instead ofv0/d/sha256/{hash}. Existing objects remain retrievable. - Experimental:
signalandsignalWithStartcalled from a@TemporalOperationhandler now reuse the
operation's request ID, so a retried Nexus task no longer delivers the same signal twice. Signals sent from other
Nexus operation handlers keep an independent request ID per call and are not deduplicated. - Moved the Spring AI integration to temporalio/ai-integrations.
io.temporal:temporal-spring-ainow publishes a one-time relocation POM toio.temporal:spring-ai:0.1.0;
the integration is versioned independently of the SDK. The standalone release requires Java 17+, Spring AI 2,
Spring Boot 4, and Temporal Java SDK 1.40.0+. Spring AI 1 / Spring Boot 3 applications should remain on
io.temporal:temporal-spring-ai:1.40.xuntil they migrate. Existing Spring AI 1 workflow histories are not
replay-compatible; complete those executions or use separate worker deployments. - Release notes for all future releases are now in a single CHANGELOG.md file.
releasesdirectory with old release
notes is kept for historical reference. - Added versioned scheduling for asynchronous Temporal stub calls. When enabled, switching between a stub method
reference such asAsync.function(activities::first)and an equivalent lambda such as
Async.function(() -> activities.first())preserves command order during replay. The call runs on a workflow thread,
so workflow outbound interceptors can wait while scheduling it. The flag remains disabled by default, and existing
unflagged histories retain their previous behavior. TemporalDevServer,TemporalDevServerOptions,TestWorkflowEnvironment.startLocal, and theuseDevServermethods
ofTestWorkflowRuleandTestWorkflowExtensionare no longer marked experimental.TemporalDevServerOptionsremain
specific to the Temporal CLI dev server implementation and may no longer be valid if that implementation changes.
Fixed
- Skipped
Workflow.mutableSideEffectcalls made with the new recovery flag enabled no longer
leave invalid marker commands after cache eviction or a worker restart. The flag remains disabled
by default in this release to preserve replay compatibility during SDK rollout. RetryOptions.mergenow accepts partially configured policies, preserving unset initial intervals
and backoff coefficients until validation or annotation merging supplies them.- Fixed workflow task completion pagination, which threw
UnsupportedOperationExceptionbefore
sending the first page. A completion that needed pagination timed out on every attempt instead
of being sent. The same fix letsRpcRetryOptions.newBuilder(options).addDoNotRetry(...)extend
existing options, which also threwUnsupportedOperationException. RpcRetryOptionsno longer changes when the builder that created it is reused. Previously,
addDoNotRetrycalls made afterbuild()orvalidateBuildWithDefaults()also appeared in
the options already built.- Schedule action headers are now preserved when describing and updating a schedule.
ActivityClientnow sends thetemporal-namespacegRPC header likeWorkflowClientandScheduleClientdo,
so standalone activity calls are no longer rejected withPERMISSION_DENIEDby namespace-scoped auth (e.g.
Temporal Cloud API keys).- The Java 8 entry of
Jackson3JsonPayloadConverterin the multi-release jar now declares the same public API as the
Java 17 class, including theJsonMapperconstructor andnewDefaultJsonMapper(boolean). Tools that compile against
the base entry, such as IntelliJ's build system, no longer rejectnew Jackson3JsonPayloadConverter(mapper). - Kotlin
Asyncmethod references compiled with Kotlin 2.4 now retain their inline behavior,
preventingNonDeterministicExceptionwhen replaying workflows started with Kotlin 2.2. For
workflows already started with Kotlin 2.4 and SDK 1.40 or earlier, set the
temporal.kotlin.disableStaticAdapterUnwrappingJVM system property to preserve the previous
behavior during replay. - Test server now honors retry expiration deadlines that fall exactly on a whole second. Previously such deadlines were
ignored and retries were scheduled past them instead of failing withRETRY_STATE_TIMEOUT. - Worker heartbeats now list each plugin name once. Previously a plugin registered on both the
WorkflowClientand theWorkerFactorywas listed twice. - Activity workers now report
activity_schedule_to_start_latencyonce per activity task, measured up to the time the
worker receives the task. Previously each task reported it twice, once with the activity type and workflow type tags,
and measured it up to the server start time.