Skip to main content

Available state change hooks

Note that the on_rollback hook for tasks is not a proper state change hook but instead is a transaction lifecycle hook. Rollback hooks accept one argument representing the transaction for the task.

Send a notification when a workflow run fails

To send a notification when a flow or task run fails, you can specify a on_failure hook.
Retries are configured in this example, so the on_failure hook will not run until all retries have completed and the flow run enters a Failed state.
State change hooks execute client sideState change hooks run in the same process as your workflow and execution cannot be guaranteed. For more robust execution of logic in response to state changes, use an Automation.

Execute code when a task starts running

The on_running hook executes when a task enters a Running state, before the task body executes. This is useful for logging, metrics, or setting up runtime state:
Note that on_running hooks execute synchronously before the task body runs. If your hook takes 10 seconds, the task waits 10 seconds before starting. When retries are configured, on_running hooks fire on each retry attempt, including the initial run. For example, a task configured with retries=2 will trigger its on_running hooks up to three times: once on the initial run and once for each retry attempt.

Log from state change hooks

State change hooks run outside the active flow or task run context. This means get_run_logger() will raise a MissingContextError if called inside a hook. To emit logs from a hook that appear in the Prefect UI, use flow_run_logger (or task_run_logger for task hooks) from prefect.logging.loggers. These functions create a logger tied to the run using the parameters your hook already receives:
For more information on logging options, see How to add logging.

Pass kwargs to state change hooks

You can compose the with_options method to effectively pass arbitrary **kwargs to your hooks: