On Failure Step

The On Failure Step is a special step in Hatchet workflows that allows you to define a function to be executed in the event that any step 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 Step

You can define an On Failure Step on your Workflow using the Hatchet client libraries:

# This workflow will fail because the step will throw an error
# we define an onFailure step to handle this case
 
 
@hatchet.workflow(on_events=["user:create"])
class OnFailureWorkflow:
    @hatchet.step(timeout="1s")
    def step1(self, context: Context) -> None:
        # 👀 this step will always raise an exception
        raise Exception("step1 failed")
 
    # 👀 After the workflow fails, this special step will run
    @hatchet.on_failure_step()
    def on_failure(self, context: Context) -> dict[str, str]:
        # 👀 we can do things like perform cleanup logic
        # or notify a user here
        return {"status": "success"}
 
 

In the above examples, the on failure step is defined separately from the main workflow steps. It will be executed only if any of the main workflow steps fail.

Use Cases

Some common use cases for the On Failure Step 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 Step, you can handle workflow failures gracefully and ensure that necessary actions are taken in case of errors.

Example: Sending a Slack Notification on Failure

@hatchet.on_failure_step()
def on_failure(self, context):
    slack_client.send_message(
        f"Workflow {context.workflow_run_id()} failed"
    )

In this example, the On Failure Step sends a Slack notification with details about the failed workflow, including the workflow run ID which can be used to find the run in the Hatchet Dashboard.

By leveraging the On Failure Step, you can enhance the reliability and observability of your workflows, ensuring that failures are handled appropriately and relevant stakeholders are notified.