Error Handling - Temporal Nexus
Temporal Nexus is available in Public Preview for Temporal Cloud and self-hosted deployments.
Nexus Operations can return an error for a caller Workflow to handle. If an asynchronous Nexus Operation starts a Workflow that returns an error, it will be propagated back to the caller Workflow.
Errors in Nexus handlers
In Temporal, a user-defined Nexus handler is primarily responsible for starting a Nexus Operation. Nexus handlers run in a Temporal Worker and use Temporal SDK builder functions like New-Sync-Operation or New-Workflow-Run-Operation to start an Operation. Nexus handlers may return different error types. Nexus Operations can end up in completed, failed, canceled, and timed out states.
The Nexus Machinery breaks up the Nexus Operation lifecycle into one or more Nexus Tasks that a Nexus handler is responsible for processing. It creates a Nexus Task to start an Operation and may create additional Nexus Tasks, for example to cancel a long-running asynchronous Operation.
By default, Nexus handler errors are considered retryable, unless specified below:
- Application Failures marked as non-retryable.
- Unsuccessful Operation errors that can resolve an operation as either failed or canceled.
- Non-retryable Nexus errors.
For example, if an unknown error is returned from a Nexus handler it will be classified as a retryable error.
When an error is received by the caller's Nexus Machinery:
- If a non-retryable error is returned, the caller Workflow will have a NexusOperationFailed event added to its Workflow History.
- If a retryable error is returned, the Nexus Machinery will automatically retry the Nexus Task, as discussed in automatic retries. These errors are visible to the caller Workflow as part of integrated execution debugging in Pending Operations.
To avoid infinite automatic retries and improve semantics, custom Nexus handlers should return a specific Nexus error type.
See errors in Nexus Operations for additional details.
Nexus error handling in caller Workflows
A Nexus Operation Failure is delivered to the Workflow Execution when a Nexus Operation fails. It contains information about the failure and the Nexus Operation Execution; for example, the Nexus Operation name and Nexus Operation ID. The reason for the failure is in the message and in the underlying cause is typically an Application Error or a Canceled Error.