Skip to main content

Class: ApplicationFailure

ApplicationFailures are used to communicate application-specific failures in Workflows and Activities.

The type property is matched against RetryPolicy.nonRetryableErrorTypes to determine if an instance of this error is retryable. Another way to avoid retrying is by setting the nonRetryable flag to true.

In Workflows, if you throw a non-ApplicationFailure, the Workflow Task will fail and be retried. If you throw an ApplicationFailure, the Workflow Execution will fail.

In Activities, you can either throw an ApplicationFailure or another Error to fail the Activity Task. In the latter case, the Error will be converted to an ApplicationFailure. The conversion is done as following:

  • type is set to error.constructor?.name ?? error.name
  • message is set to error.message
  • nonRetryable is set to false
  • details are set to null
  • cause is set to error.cause when it is an Error
  • stack trace is copied from the original error

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

Extends​

Constructors​

Constructor​

new ApplicationFailure(message?, type?, nonRetryable?, details?, cause?, nextRetryDelay?, category?): ApplicationFailure

Alternatively, use fromError or create.

Parameters​

message?​

string | null

type?​

string | null

nonRetryable?​

boolean | null

details?​

unknown[] | null

cause?​

Error

nextRetryDelay?​

Duration | null

category?​

"BENIGN" | null

Returns​

ApplicationFailure

Overrides​

TemporalFailure.constructor

Properties​

category?​

readonly optional category?: "BENIGN" | null

cause?​

readonly optional cause?: Error

Inherited from​

TemporalFailure.cause

details?​

readonly optional details?: unknown[] | null

failure?​

optional failure?: IFailure

The original failure that constructed this error.

Only present if this error was generated from an external operation.

Inherited from​

TemporalFailure.failure

message​

message: string

Inherited from​

TemporalFailure.message

name​

name: string

Inherited from​

TemporalFailure.name

nextRetryDelay?​

readonly optional nextRetryDelay?: Duration | null

nonRetryable?​

readonly optional nonRetryable?: boolean | null

stack?​

optional stack?: string

Inherited from​

TemporalFailure.stack

type?​

readonly optional type?: string | null

stackTraceLimit​

static stackTraceLimit: number

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from​

TemporalFailure.stackTraceLimit

Methods​

captureStackTrace()​

static captureStackTrace(targetObject, constructorOpt?): void

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters​

targetObject​

object

constructorOpt?​

Function

Returns​

void

Inherited from​

TemporalFailure.captureStackTrace

create()​

static create(options): ApplicationFailure

Create a new ApplicationFailure.

By default, will be retryable (unless its type is included in RetryPolicy.nonRetryableErrorTypes).

Parameters​

options​

ApplicationFailureOptions

Returns​

ApplicationFailure

fromError()​

static fromError(error, overrides?): ApplicationFailure

Create a new ApplicationFailure from an Error object.

First calls `ensureApplicationFailure(error)` and then overrides any fields provided in overrides.

Parameters​

error​

unknown

overrides?​

ApplicationFailureOptions

Returns​

ApplicationFailure

nonRetryable()​

static nonRetryable(message?, type?, ...details): ApplicationFailure

Get a new ApplicationFailure with the nonRetryable flag set to true.

When thrown from an Activity or Workflow, the Activity or Workflow will not be retried (even if type is not listed in RetryPolicy.nonRetryableErrorTypes).

Parameters​

message?​

string | null

Optional error message

type?​

string | null

Optional error type

details​

...unknown[]

Optional details about the failure. Serialized by the Worker's PayloadConverter.

Returns​

ApplicationFailure

prepareStackTrace()​

static prepareStackTrace(err, stackTraces): any

Parameters​

err​

Error

stackTraces​

CallSite[]

Returns​

any

See​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from​

TemporalFailure.prepareStackTrace

retryable()​

static retryable(message?, type?, ...details): ApplicationFailure

Get a new ApplicationFailure with the nonRetryable flag set to false. Note that this error will still not be retried if its type is included in RetryPolicy.nonRetryableErrorTypes.

Parameters​

message?​

string | null

Optional error message

type?​

string | null

Optional error type (used by RetryPolicy.nonRetryableErrorTypes)

details​

...unknown[]

Optional details about the failure. Serialized by the Worker's PayloadConverter.

Returns​

ApplicationFailure