On-Failure Tasks

The on-failure task is a special type of task in Hatchet workflows that allows you to define a function to be executed in the event that any task in the main workflow fails. This feature enables you to handle errors, perform cleanup tasks, or trigger notifications in case of workflow failures.

Defining an on-failure task

You can define an on-failure task on your workflow the same as you’d define any other task:

examples/on_failure/worker.py

# This workflow will fail because the step will throw an error
# we define an onFailure step to handle this case

on_failure_wf = hatchet.workflow(name="OnFailureWorkflow")


@on_failure_wf.task(execution_timeout=timedelta(seconds=1))
def step1(input: EmptyModel, ctx: Context) -> None:
    raise Exception(ERROR_TEXT)


@on_failure_wf.on_failure_task()
def on_failure(input: EmptyModel, ctx: Context) -> dict[str, str]:
    # or notify a user here

    print(ctx.task_run_errors)

    return {"status": "success"}

💡

Note: Only one on-failure task can be defined per workflow.

src/v1/examples/on_failure/workflow.ts

export const failureWorkflow = hatchet.workflow({
  name: 'always-fail',
});

failureWorkflow.task({
  name: 'always-fail',
  fn: async () => {
    throw new Error('intentional failure');
  },
});

failureWorkflow.onFailure({
  name: 'on-failure',
  fn: async (input, ctx) => {
    console.log('onFailure for run:', ctx.workflowRunId());
    return {
      'on-failure': 'success',
    };
  },
});

examples/on-failure/main.go

// This workflow will fail because the step will throw an error
// we define an onFailure step to handle this case

func StepOne(ctx worker.HatchetContext) (result *stepOneOutput, err error) {
	return nil, fmt.Errorf("test on failure")
}

func OnFailure(ctx worker.HatchetContext) (result *stepOneOutput, err error) {
	// run cleanup code or notifications here

	fmt.Println(ctx.StepRunErrors())

	return &stepOneOutput{
		Message: "Failure!",
	}, nil
}

func main() {
	// ...
	err = w.On(
		worker.NoTrigger(),
		&worker.WorkflowJob{
			Name:        "on-failure-workflow",
			Description: "This runs at a scheduled time.",
			Steps: []*worker.WorkflowStep{
				worker.Fn(StepOne).SetName("step-one"),
			},
			OnFailure: &worker.WorkflowJob{
				Name:        "scheduled-workflow-failure",
				Description: "This runs when the scheduled workflow fails.",
				Steps: []*worker.WorkflowStep{
					worker.Fn(OnFailure).SetName("on-failure"),
				},
			},
		},
	)

	// ...
}

In the examples above, the on-failure task will be executed only if any of the main workflow task fail.

Use Cases

Some common use cases for the on-failure task include:

Performing cleanup tasks after a workflow failure
Sending notifications or alerts about the failure
Logging additional information for debugging purposes
Triggering a compensating action or a fallback workflow

By utilizing the on-failure task, you can handle workflow failures gracefully and ensure that necessary actions are taken in case of errors.

Timeouts Retry Policies

We use cookies

On-Failure Tasks

Defining an on-failure task

Use Cases