Skip to main content

Interface: ReplayWorkerOptions


WorkerOptions with inapplicable-to-replay fields removed.


  • Omit<WorkerOptions, "connection" | "namespace" | "taskQueue" | "activities" | "maxConcurrentActivityTaskExecutions" | "maxConcurrentLocalActivityExecutions" | "maxConcurrentWorkflowTaskExecutions" | "maxConcurrentActivityTaskPolls" | "maxConcurrentWorkflowTaskPolls" | "nonStickyToStickyPollRatio" | "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 WorkerOptions.useVersioning. It will also populate the binaryChecksum field on older servers.

ℹī¸ Required if useVersioning is true.

⚠ī¸ NOTE: When used with versioning, you must pass this build ID to updateBuildIdCompatibility. Otherwise, this Worker will not pick up any tasks.


@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.

When bundling workflows ahead of time, make sure to provide custom payload and failure converter paths as options to bundleWorkflowCode.

Inherited from​



â€ĸ Optional enableSDKTracing: boolean


SDK tracing is no longer supported. This option is ignored.

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.

Interceptors are called in order, from the first to the last, each one making the call to the next one, and the last one calling the original (SDK provided) function.

By default, WorkflowInboundLogInterceptor is 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 BundleOptions.workflowInterceptorModules when calling bundleWorkflowCode.

Before v1.9.0, calling appendDefaultInterceptors() was required when registering custom interceptors in order to preserve SDK's logging interceptors. This is no longer the case.

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: We strongly recommend enabling the Reuse V8 Context execution model, and there is currently no known reason not to use it. Support for the legacy execution model may get removed at some point in the future. Please report any issue that requires you to disable reuseV8Context.



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.

Sink names starting with __temporal_ are reserved for use by the SDK itself. Do not register or use such sink. Registering a sink named defaultWorkerLogger to redirect workflow logs to a custom logger is deprecated. Register a custom logger through Runtime.logger instead.

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 BundleOptions.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 Worker.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 Worker.create via the workflowBundle option.

See for more information.

Inherited from​