Class: ApplicationFailure

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

Hierarchy

• TemporalFailure

  ↳ ApplicationFailure

Constructors

constructor

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

Alternatively, use fromError or create.

Parameters

Name	Type
message?	null | string
type?	null | string
nonRetryable?	null | boolean
details?	null | unknown[]
cause?	Error
nextRetryDelay?	null | Duration
category?	null | "BENIGN"

Returns

ApplicationFailure

Overrides

TemporalFailure.constructor

Properties

category

• Optional Readonly category: null | "BENIGN"

---

cause

• Optional Readonly cause: Error

Inherited from

TemporalFailure.cause

---

details

• Optional Readonly details: null | unknown[]

---

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

• Optional Readonly nextRetryDelay: null | Duration

---

nonRetryable

• Optional Readonly nonRetryable: null | boolean

---

stack

• Optional stack: string

Inherited from

TemporalFailure.stack

---

type

• Optional Readonly type: null | string

---

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

▸ 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

Name	Type
targetObject	object
constructorOpt?	Function

Returns

void

Inherited from

TemporalFailure.captureStackTrace

---

create

▸ create(options): ApplicationFailure

Create a new ApplicationFailure.

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

Parameters

Name	Type
options	ApplicationFailureOptions

Returns

ApplicationFailure

---

fromError

▸ 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

Name	Type
error	unknown
overrides?	ApplicationFailureOptions

Returns

ApplicationFailure

---

nonRetryable

▸ 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

Name	Type	Description
message?	null | string	Optional error message
type?	null | string	Optional error type
...details	unknown[]	Optional details about the failure. Serialized by the Worker's PayloadConverter.

Returns

ApplicationFailure

---

prepareStackTrace

▸ prepareStackTrace(err, stackTraces): any

Parameters

Name	Type
err	Error
stackTraces	CallSite[]

Returns

any

See

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

Inherited from

TemporalFailure.prepareStackTrace

---

retryable

▸ 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

Name	Type	Description
message?	null | string	Optional error message
type?	null | string	Optional error type (used by RetryPolicy.nonRetryableErrorTypes)
...details	unknown[]	Optional details about the failure. Serialized by the Worker's PayloadConverter.

Returns

ApplicationFailure