Skip to main content

What is a Failure?

A Failure is Temporal's representation of various types of errors that occur in the system.

There are different types of Failures, and each has a different type in the SDKs and different information in the protobuf messages (which are used to communicate with the Cluster and appear in Event History).

Temporal Failure​

Most SDKs have a base class that the other Failures extend:

The base Failure proto message has these fields:

  • string message
  • string stack_trace
  • string source: The SDK this Failure originated in (for example, "TypeScriptSDK"). In some SDKs, this field is used to rehydrate the stack trace into an exception object.
  • Failure cause: The Failure message of the cause of this Failure (if applicable).
  • Payload encoded_attributes: Contains the encoded message and stack_trace fields when using a Failure Converter.

Application Failure​

Workflow and Activity code use Application Failures to communicate application-specific failures that happen. This is the only type of Failure created and thrown by user code.

Throw from Workflows​

Only Workflow errors that are Temporal Failures will cause the Worklow Execution to fail: all other errors will cause the Workflow Task to fail and be retried (except for Go, where any error returned from the Workflow will fail the Execution, and a panic will fail the Task). Most types of Temporal Failures automatically occur, like a Cancelled Failure when the Workflow is Cancelled or an Activity Failure when an Activity Fails. You can also explicitly fail the Workflow Execution by throwing (or returning, depending on the SDK) an Application Failure.

Throw from Activities​

In Activities, you can either throw an Application Failure or another Error to fail the Activity Task. In the latter case, the error will be converted to an Application Failure. During conversion, the following Application Failure fields are set:

  • type is set to the error's type name
  • message is set to the error message
  • non_retryable is set to false
  • details are left unset
  • cause is a Failure converted from the error's cause property
  • stack trace is copied

When an Activity Execution fails, the Application Failure from the last Activity Task will be the cause field of the ActivityFailure thrown in the Workflow.

Non-retryable​

When an Activity or Workflow throws an Application Failure, the Failure's type field is matched against a Retry Policy's list of non-retryable errors to determine whether to retry the Activity or Workflow. Activities and Workflow can also avoid retrying by setting an Application Failure's non_retryable flag to true.

Cancelled Failure​

When Cancellation has been requested of a workflow or activity, SDKs represent this to the user in language-specific ways.

When a Workflow or Activity has been successfully Cancelled, a Cancelled Failure will be the cause field of the Activity Failure or "Workflow failed" error.

Activity Failure​

An Activity Failure is delivered to the Workflow Execution when an Activity fails. It contains information about the failure and the Activity Execution, for example the Activity Type and Id. The reason for the failure will be in the cause field. For example, if an Activity Execution times out, the cause will be a Timeout Failure.

Child Workflow Failure​

A Child Workflow Failure is delivered to the Workflow Execution when a Child Workflow Execution fails. It contains information about the failure and the Child Workflow Execution, for example the Workflow Type and Id. The reason for the failure will be in the cause field.

Timeout Failure​

Represents the timeout of an Activity or Workflow Execution.

When an Activity times out, the last Heartbeat details it emitted is attached.

Terminated Failure​

Used as the cause when a Workflow has been Terminated.

Server Failure​

Used for errors that originated in the Cluster.