Handle Errors in Workflows

Handle Errors in Workflows

Understand when workflow catch blocks run

Steps and evaluators run as Temporal Activities. Temporal applies their configured retry policy before returning a successful result or throwing a final failure to workflow code.

A workflow catch around a step therefore runs only after the step has exhausted its Activity retries. Catching that failure does not disable or bypass the Activity retry policy.

The catch block decides what the workflow does with the final failure:

• Return a fallback value.
• Run an alternative step.
• Record a partial failure and continue.
• Handle an expected error type.
• Rethrow the error and fail the workflow.

Let unexpected failures propagate

Do not add a catch block that only wraps or logs an error. It can discard Temporal's failure type, cause chain, and retry metadata.

// Avoid: replaces the original Temporal failure chain.
try {
  return await fetchData( input );
} catch ( error ) {
  throw new Error( `Fetch failed: ${error.message}` );
}

When the workflow cannot recover, let the step failure propagate:

export default workflow( {
  name: 'fetch_workflow',
  fn: async input => fetchData( input )
} );

If a catch block handles only known failures, always rethrow everything else.