Skip to main content

Interface: ReplayWorkerOptions


WorkerOptions with inapplicable-to-replay fields removed.


  • Omit<WorkerOptions, "connection" | "namespace" | "taskQueue" | "activities" | "maxConcurrentActivityTaskExecutions" | "maxConcurrentLocalActivityExecutions" | "maxConcurrentWorkflowTaskExecutions" | "maxHeartbeatThrottleInterval" | "defaultHeartbeatThrottleInterval" | "debugMode" | "enableNonLocalActivities" | "maxActivitiesPerSecond" | "maxTaskQueueActivitiesPerSecond" | "stickyQueueScheduleToStartTimeout" | "maxCachedWorkflows" | "useVersioning">

    â†ŗ ReplayWorkerOptions



â€ĸ Optional buildId: string

A string that should be unique to the exact worker code/binary being executed.

This is used to uniquely identify the worker's code for a handful of purposes, including the worker versioning feature if you have opted into that with useVersioning. It will also populate the binaryChecksum field on older servers.

ℹī¸ Required if useVersioning is true.


@temporalio/worker package name and version + checksum of workflow bundle's code

Inherited from​



â€ĸ Optional bundlerOptions: Object

Type declaration​

ignoreModules?string[]List of modules to be excluded from the Workflows bundle. Use this option when your Workflow code references an import that cannot be used in isolation, e.g. a Node.js built-in module. Modules listed here MUST not be used at runtime. > NOTE: This is an advanced option that should be used with care.
webpackConfigHook?(config: Configuration) => ConfigurationBefore Workflow code is bundled with Webpack, webpackConfigHook is called with the Webpack configuration object so you can modify it.

Inherited from​



â€ĸ Optional dataConverter: DataConverter

Provide a custom DataConverter.

Inherited from​



â€ĸ Optional enableSDKTracing: boolean

Enable opentelemetry tracing of SDK internals like polling, processing and completing tasks.

Useful for debugging issues with the SDK itself.

For completeness the Rust Core also generates opentelemetry spans which connect to the Worker's spans. Configure CoreOptions.telemetryOptions to enable tracing in Core.



Inherited from​



â€ĸ Optional identity: string

A human-readable string that can identify your worker

Note that in most production environments, the identity value set by default may be unhelpful for traceability purposes. It is highly recommended that you set this value to something that will allow you to efficiently identify that particular Worker container/process/logs in your infrastructure (ex: the task ID allocated to this container by your orchestrator).



Inherited from​



â€ĸ Optional interceptors: WorkerInterceptors

A mapping of interceptor type to a list of factories or module paths.

By default, ActivityInboundLogInterceptor and WorkflowInboundLogInterceptor are installed. If you wish to customize the interceptors while keeping the defaults, use appendDefaultInterceptors.

When using workflowBundle, these Workflow interceptors (WorkerInterceptors.workflowModules) are not used. Instead, provide them via workflowInterceptorModules when calling bundleWorkflowCode.

Inherited from​



â€ĸ Optional maxConcurrentActivityTaskPolls: number

Maximum number of Activity tasks to poll concurrently.

Increase this setting if your Worker is failing to fill in all of its maxConcurrentActivityTaskExecutions slots despite a backlog of Activity Tasks in the Task Queue (ie. due to network latency). Can't be higher than maxConcurrentActivityTaskExecutions.


min(2, maxConcurrentActivityTaskExecutions)

Inherited from​



â€ĸ Optional maxConcurrentWorkflowTaskPolls: number

Maximum number of Workflow Tasks to poll concurrently.

In general, a Workflow Worker's performance is mostly network bound (due to communication latency with the Temporal server). Polling multiple Workflow Tasks concurrently helps compensate for this latency, by ensuring that the Worker is not starved waiting for the server to return new Workflow Tasks to execute.

This setting is highly related with maxConcurrentWorkflowTaskExecutions. In various performance tests, we generally got optimal performance by setting this value to about half of maxConcurrentWorkflowTaskExecutions. Your millage may vary.

Setting this value higher than needed may have negative impact on the server's performance. Consequently, the server may impose a limit on the total number of concurrent Workflow Task pollers.

General guidelines:

  • By default, set this value to half of maxConcurrentWorkflowTaskExecutions.
  • Increase if actual number of Workflow Tasks being processed concurrently is lower than maxConcurrentWorkflowTaskExecutions despite a backlog of Workflow Tasks in the Task Queue.
  • Keep this value low for Task Queues which have very few concurrent Workflow Executions.

Can't be higher than maxConcurrentWorkflowTaskExecutions, and can't be lower than 2.


min(10, maxConcurrentWorkflowTaskExecutions)

Inherited from​



â€ĸ Optional replayName: string

A optional name for this replay worker. It will be combined with an incremental ID to form a unique task queue for the replay worker.




â€ĸ Optional reuseV8Context: boolean

Toggle whether to reuse a single V8 context for the workflow sandbox.

Context reuse significantly decreases the amount of resources taken up by workflows. From running basic stress tests we've observed 2/3 reduction in memory usage and 1/3 to 1/2 in CPU usage with this feature turned on.

Note that we plan to turn this option on by default starting with 1.9.0.


false (will change in the future)

Inherited from​



â€ĸ Optional showStackTraceSources: boolean

Whether or not to send the sources in enhanced stack trace query responses



Inherited from​



â€ĸ Optional shutdownForceTime: Duration

Time to wait before giving up on graceful shutdown and forcefully terminating the worker.

After this duration, the worker will throw GracefulShutdownPeriodExpiredError and any running activities and workflows will not be cleaned up. It is recommended to exit the process after this error is thrown.

Use this option if you must guarantee that the worker eventually shuts down.


number of milliseconds or ms-formatted string

Inherited from​



â€ĸ Optional shutdownGraceTime: Duration

Time to wait for pending tasks to drain after shutdown was requested.

In-flight activities will be cancelled after this period and their current attempt will be resolved as failed if they confirm cancellation (by throwing a CancelledFailure or AbortError).


number of milliseconds or ms-formatted string



Inherited from​



â€ĸ Optional sinks: InjectedSinks<any>

Registration of a SinkFunction, including per-sink-function options.

Sinks are a mechanism for exporting data out of the Workflow sandbox. They are typically used to implement in-workflow observability mechanisms, such as logs, metrics and traces.

To prevent non-determinism issues, sink functions may not have any observable side effect on the execution of a workflow. In particular, sink functions may not return values to the workflow, nor throw errors to the workflow (an exception thrown from a sink function simply get logged to the Runtime's logger).

For similar reasons, sink functions are not executed immediately when a call is made from workflow code. Instead, calls are buffered until the end of the workflow activation; they get executed right before returning a completion response to Core SDK. Note that the time it takes to execute sink functions delays sending a completion response to the server, and may therefore induce Workflow Task Timeout errors. Sink functions should thus be kept as fast as possible.

Sink functions are always invoked in the order that calls were maded in workflow code. Note however that async sink functions are not awaited individually. Consequently, sink functions that internally perform async operations may end up executing concurrently.

Please note that sink functions only provide best-effort delivery semantics, which is generally suitable for log messages and general metrics collection. However, in various situations, a sink function call may execute more than once even though the sink function is configured with callInReplay: false. Similarly, sink function execution errors only results in log messages, and are therefore likely to go unnoticed. For use cases that require at-least-once execution guarantees, please consider using local activities instead. For use cases that require exactly-once or at-most-once execution guarantees, please consider using regular activities.

The SDK itself may register sinks functions required to support workflow features. At the moment, the only such sink is 'defaultWorkerLogger', which is used by the workflow context logger (ie. and friends); other sinks may be added in the future. You may override these default sinks by explicitely registering sinks with the same name.

Inherited from​



â€ĸ Optional workflowBundle: WorkflowBundleOption

Use a pre-built bundle for Workflow code. Use bundleWorkflowCode to generate the bundle. The version of @temporalio/worker used when calling bundleWorkflowCode must be the exact same version used when calling Worker.create.

This is the recommended way to deploy Workers to production.

See for more information.

When using this option, workflowsPath, bundlerOptions and any Workflow interceptors modules provided in * interceptors are not used. To use workflow interceptors, pass them via workflowInterceptorModules when calling bundleWorkflowCode.

Inherited from​



â€ĸ Optional workflowThreadPoolSize: number

Controls the number of threads to be created for executing Workflow Tasks.

Adjusting this value is generally not useful, as a Workflow Worker's performance is mostly network bound (due to communication latency with the Temporal server) rather than CPU bound. Increasing this may however help reduce the probability of Workflow Tasks Timeouts in some particular situations, for example when replaying many very large Workflow Histories at the same time. It may also make sense to tune this value if maxConcurrentWorkflowTaskExecutions and maxConcurrentWorkflowTaskPolls are increased enough so that the Worker doesn't get starved waiting for Workflow Tasks to execute.

There is no major downside in setting this value _slightly) higher than needed; consider however that there is a per-thread cost, both in terms of memory footprint and CPU usage, so arbitrarily setting some high number is definitely not advisable.

Threading model​

All interactions with Core SDK (including polling for Workflow Activations and sending back completion results) happens on the main thread. The main thread then dispatches Workflow Activations to some worker thread, which create and maintain a per-Workflow isolated execution environments (aka. the Workflow Sandbox), implemented as VM contexts.

When reuseV8Context is disabled, a new VM context is created for each Workflow handled by the Worker. Creating a new VM context is a relatively lengthy operation which blocks the Node.js event loop. Using multiple threads helps compensate the impact of this operation on the Worker's performance.

When reuseV8Context is enabled, a single VM context is created for each worker thread, then reused for every Workflows handled by that thread (per-Workflow objects get shuffled in and out of that context on every Workflow Task). Consequently, there is generally no advantage in using multiple threads when reuseV8Context is enabled.

If more than one thread is used, Workflows will be load-balanced evenly between worker threads on the first Activation of a Workflow Execution, based on the number of Workflows currently owned by each worker thread; futher Activations of that Workflow Execution will then be handled by the same thread, until the Workflow Execution gets evicted from cache.


1 if 'reuseV8Context' is enabled; 2 otherwise. Ignored if debugMode is enabled.

Inherited from​



â€ĸ Optional workflowsPath: string

Path to look up workflows in, any function exported in this path will be registered as a Workflows in this Worker.

If this option is provided to create, Webpack compliation will be triggered.

This option is typically used for local development, for production it's preferred to pre-build the Workflow bundle and pass that to create via the workflowBundle option.

See for more information.

Inherited from​