failures

26 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Non-Temporal errors automatically converted to Application Failure

Any non-Temporal error thrown from an Activity is automatically converted to an Application Failure. During this conversion, the error's type name, message, and call stack are preserved, and non_retryable is set to false.

Platform failures vs application failures definition

Temporal categorizes failures into two types: Platform failures occur due to infrastructure issues (server outages, network interruptions, Worker crashes) and are handled transparently by Temporal's Durable Execution through forward recovery (retrying the failed operation). Application failures are generated by application code (invalid input, business rule violations, failed external service calls) and do not resolve on their own through retries alone; they often require backward recovery to undo work.

Temporal failure types list

Temporal SDKs represent failures with typed error objects. The failure types are: Application Failure (raised by code for application-specific errors), Activity Failure (wraps an error from Activity Execution with the underlying error in the cause field), Child Workflow Failure (wraps an error from Child Workflow Execution), Timeout Failure (occurs when Activity or Workflow exceeds configured timeout), Cancelled Failure (results from cancellation of Workflow, Activity, or Timer), Terminated Failure (occurs when Workflow Execution is forcefully terminated), and Server Failure (originates from Temporal Service itself).

Do not extend failure base classes

Do not extend the base failure class or any of its children in code. The provided classes are designed to work with Temporal's serialization mechanism, which converts failures to Protocol Buffer messages for communication across process and language boundaries. Custom subclasses can break this serialization and lead to unexpected behavior.

Application Failure fields

When you throw an Application Failure, you can set these fields: message (human-readable description of the error), type (a string that categorizes the failure such as 'InvalidInput' or 'InsufficientFunds'), non_retryable (flag that prevents the operation from being retried regardless of Retry Policy), and details (additional data about the failure).

Failure Converter handles sensitive information

When Temporal returns a failure, the default Failure Converter copies error messages and stack traces as plain text, accessible in the Web UI and through the CLI. If errors might contain sensitive information, you can encrypt the message and stack trace by configuring a custom Failure Converter with a codec.

Workflow Task failure vs Workflow Execution failure

When an error occurs in Workflow code, it produces one of two outcomes: A Workflow Task failure is caused by non-Temporal errors (null reference, division by zero, type errors, non-determinism errors), is retried automatically, preserves Workflow state so you can fix the bug and redeploy without losing progress, and is typically caused by a bug in Workflow code. A Workflow Execution failure is caused by Temporal failures thrown by code such as Application Failure, is not retried, puts Workflow in 'Failed' state permanently with no more attempts, and is typically caused by a permanent business logic failure where retrying with the same input will not help.

Workflow Task failure retry process

When a Workflow Task failure is retried, the Worker removes the Workflow Execution from its cache, the Temporal Service schedules a new Workflow Task on the original Task Queue, and a Worker picks up the Task and replays the Workflow Execution from Event History to restore the correct state before continuing.

Activity error wrapping in Workflow

When an Activity fails, Temporal wraps the error in an Activity Failure before delivering it to the Workflow. The Activity Failure provides context about the failure, including the Activity Type, the number of retry attempts, and the original cause. The original error is in the cause field. For example, if an Activity throws an Application Failure with type 'InvalidInput', the Workflow receives an Activity Failure whose cause is that Application Failure. If an Activity times out instead, the cause is a Timeout Failure.

Child Workflow error wrapping pattern

When a Child Workflow fails, a Child Workflow Failure is delivered to the parent Workflow, with the original error in the cause field.

Cancelled Failure state exception

If a Temporal failure propagates unhandled through Workflow code, it fails the Workflow Execution. The exception is Cancelled Failure, which puts the Workflow in 'Cancelled' state instead of 'Failed'.

Outermost error type determines retryability

When an Activity returns an error, the SDK inspects the outermost error to decide how to represent the failure to the Temporal Service. The SDK performs a type check on the outermost error and converts it to a Protocol Buffer Failure message. If the outermost error is an Application Failure, the SDK preserves its non_retryable flag and type field in the resulting ApplicationFailureInfo proto. If the outermost error is any other type, the SDK falls back to creating a default, retryable ApplicationFailureInfo. The Temporal Service only inspects the top-level failure_info on the Failure proto when making retry decisions and does not look at cause to determine retryability.

Wrapping Application Failure in generic error loses retryability

Wrapping an Application Failure in a generic language error silently loses the non_retryable flag. If an Activity throws a non-retryable Application Failure but your code catches it and re-throws it wrapped in a standard error, the Activity will be retried despite the original intent. To add context to an error, wrap it in another Application Failure that preserves the non_retryable flag, not in a generic language error (such as Error in TypeScript, Exception in Python, or fmt.Errorf in Go).

Detecting Workflow Task failures with TemporalReportedProblems

Use the TemporalReportedProblems Search Attribute to detect Workflows with failed Workflow Tasks. A failed Workflow Task does not cause the Workflow to fail. If a Workflow has a Task that fails and the failure is not handled, the Workflow will continue to run but will not complete. Workflows with Task failures can be identified using the Temporal Web UI Task Failures View or by searching for the TemporalReportedProblems search attribute with observability tools.

Activating Task Failures View

To enable the Task Failures View for a Namespace, you need to update the Dynamic Config for that Namespace.

Worker crash and Workflow Task Timeout handling

When a Worker dies during a Workflow Task, the Temporal Service waits for the Workflow Task Timeout, which is 10 seconds by default. After the timeout elapses, the Temporal Service records a WorkflowTaskTimedOut Event and schedules a new Workflow Task to recover.

Application-level vs platform-level failures distinction

Understanding the difference between platform-level and application-level failures is key to building reliable Temporal applications. Platform-level failures are handled automatically, while application-level failures require explicit handling.

Failure handling areas covered in Temporal documentation

Temporal's failure handling documentation covers application failures and how Temporal represents them, detecting Activity failures through timeouts and Heartbeats, detecting Workflow-level timeouts, and configuring automatic retry behavior through Retry Policies.

Nexus handler errors are retryable by default

Nexus handlers may return different error types. By default, handler errors are retryable unless they are Application Failures explicitly marked as non-retryable, Nexus Operation errors that resolve an Operation as failed or canceled, or non-retryable Nexus errors.

Retryable Nexus errors trigger automatic retries

When the caller's Nexus Machinery receives a retryable error, the Nexus Machinery automatically retries. These errors surface in Pending Operations.

Nexus Operation Failure contains operation details

When a Nexus Operation fails, the caller receives a Nexus Operation Failure containing the operation name, token, and failure reason. The cause field indicates the type of error such as Application Error or Canceled Error.

Serverless Worker failure handling for crashes

If a Serverless Worker crashes (out of memory, unhandled exception, etc.), the behavior follows standard Temporal retry semantics: the Activity Timeout fires after the configured duration, Temporal retries the Activity on another Worker, and no manual intervention is required.

Serverless Worker failure handling for provider concurrency limits

If the compute provider's capacity limit is reached (for example, AWS Lambda account concurrency or GCP Cloud Run maximum instance count), the WCI cannot add Workers beyond the limit. Tasks remain in the Task Queue backlog with no data loss, but processing slows until capacity frees up.

Workflow Task failure definition and characteristics

A Workflow Task failure means a Worker cannot successfully process a Workflow Task due to infrastructure, Workflow code, or execution environment issues (not business logic). Common causes include non-determinism, unhandled exceptions, task timeouts, invalid Commands, or bad binary checksums. The Service automatically retries the task with exponential backoff, and the Workflow Execution stays Open until a task completes, an operator terminates it, or the Workflow Execution Timeout is reached. Fixes typically involve correcting code, scaling Workers, or resolving infrastructure problems.

Workflow Execution failure definition and characteristics

A Workflow Execution failure means the Workflow's business logic determines it cannot complete. It occurs when Workflow code throws or returns an error, an Activity failure propagates uncaught, or an external system terminates or cancels the Workflow. The Workflow closes with a Failed status and does not automatically retry; if a Retry Policy is configured, the Service starts a new Run with the same Workflow ID and continues retrying until success or exhaustion. Each retry is a separate Run with its own Event History.

Workflow Task failure vs Workflow Execution failure comparison table

| Aspect | Workflow Task Failure | Workflow Execution Failure | |--------|----------------------|----------------------------| | What failed | Infrastructure or Workflow code has a bug | Business logic determined the Workflow cannot succeed | | Workflow state | Workflow Execution remains Open | Workflow Execution closes (Failed, Terminated, etc.) | | Automatic retry | Always retried automatically by the Service | Only retried if a Workflow Retry Policy is configured | | Event History | Same Event History continues to grow | Each retry run has a separate Event History | | How to resolve | Fix code/infrastructure and redeploy | May require business logic changes or external intervention | | Visibility | Shows as Workflow Task failures in history and metrics | Shows as a Failed Workflow Execution in the UI |

Give your agent this brain