docsworkflow-components

Errors​Errors

Allow your flow to continue to operate despite errors.

There are multiple ways to handle errors in Kestra, to both help you identify them and allow flows to continue to operate despite errors.

errors Component

errors is a list of tasks set at the flow level that are executed when an error occurs. You can add multiple tasks, and they are executed sequentially. This is useful for sending alerts when errors occur.

The example below sends a flow-level failure alert via Slack using the SlackIncomingWebhook task defined using the errors property.

yaml
id: errors
namespace: company.team

description: This will always fail

tasks:
  - id: failed_task
    type: io.kestra.plugin.core.execution.Fail

errors:
  - id: alert_on_failure
    type: io.kestra.plugin.notifications.slack.SlackIncomingWebhook
    url: secret('SLACK_WEBHOOK')
    payload: |
      {
        "channel": "#alerts",
        "text": "Failure alert for flow {{ flow.namespace }}.{{ flow.id }} with ID {{ execution.id }}"
      }

Two kinds of error handlers can be defined:

  • Global: error handling global to a flow that must be at the root of the flow
  • Local: error handling local to a Flowable Task, handles errors for the flowable task and its children

Global Error Handler

This flow example has a single task that fails immediately. The global error handler is then called so the 2nd task runs. Use the errorLogs() function to access the task context that failed.

yaml
id: errors
namespace: company.team

tasks:
  - id: failed
    type: io.kestra.plugin.core.execution.Fail

errors:
  - id: 2nd
    type: io.kestra.plugin.core.log.Log
    message: I'm failing {{ errorLogs()[0]['taskId'] }} # Because errorLogs() is an array, the first taskId to fail is retrieved.
    level: INFO

Local Error Handler

In this flow example, the error branch is used only if a child of the task t2 has an error. If the task t1 failed, the error branch is not used.

This can be useful to restrict error handling for a specific part of the flow and perform specific tasks like resource cleanup.

yaml
id: errors
namespace: company.team

tasks:
  - id: parent-seq
    type: io.kestra.plugin.core.flow.Sequential
    tasks:
      - id: t1
        type: io.kestra.plugin.core.debug.Return
        format: "{{task.id}} > {{taskrun.startDate}}"
      - id: t2
        type: io.kestra.plugin.core.flow.Sequential
        tasks:
          - id: t2-t1
            type: io.kestra.plugin.core.execution.Fail
        errors:
          - id: error-t1
            type: io.kestra.plugin.core.debug.Return
            format: "Error Trigger ! {{task.id}}"

allowFailure and allowWarning Property

When you execute a flow and one of its tasks fails, downstream tasks are not executed. This may not always be desirable, especially for non-critical tasks. You can resolve this by adding the allowFailure property to the task, which allows downstream tasks to continue despite an error. In this case, the execution ends in a WARNING state.

yaml
id: allow_failure
namespace: company.team

description: This flow will allow a failure of a task (imagine a flaky unit test) and will continue processing the last task, leaving the execution in a `WARNING` state.

tasks:
  - id: first
    type: io.kestra.plugin.core.debug.Return
    format: "{{ task.id }} > {{ taskrun.startDate }}"

  - id: allow_failure
    type: io.kestra.plugin.core.execution.Fail
    allowFailure: true

  - id: last
    type: io.kestra.plugin.core.debug.Return
    format: "{{ task.id }} > {{ taskrun.startDate }}"

There's also the allowWarning property which acts similar to the allowFailure property, but will finish the task and execution with a SUCCESS state.

yaml
id: allow_warning
namespace: company.team

description: This flow will allow a warning of a task (imagine a notification task) and will continue processing the last task, leaving the execution in a `WARNING` state.

tasks:
  - id: first
    type: io.kestra.plugin.core.debug.Return
    format: "{{ task.id }} > {{ taskrun.startDate }}"

  - id: allow_warning
    type: io.kestra.plugin.scripts.python.Script
    allowWarning: true
    beforeCommands:
      - pip install kestra
    script: |
      from kestra import Kestra

      logger = Kestra.logger()
      logger.warning("WARNING signals something unexpected.")

Was this page helpful?