Retries handle transient failures in your workflows. They are defined at the task level and can be configured to retry a task a certain number of times, or with a certain delay between each retry.

What are retries

Kestra provides a task retry functionality. This makes it possible to add retry behavior for any failed task run based on configurations in the flow description.

A retry on a task run will create a new task run attempt.

Example

The following example defines a retry for the retry-sample task with a maximum of 5 attempts every 15 minutes:

yaml
- id: retry-sample
  type: io.kestra.core.tasks.log.Log
  message: my output for task {{task.id}}
  timeout: PT10M
  retry:
    type: constant
    maxAttempt: 5
    interval: PT15M

Retry options for all retry types

nametypedescription
typestringRetry behavior to apply. Can be one of constant, exponential, random.
maxAttemptintegerNumber of retries performed before the system stops retrying.
maxDurationDurationMaximum delay the execution is retried. Once passed, the task is no more processed.
warningOnRetryBooleanFlag the execution as warning if any retry was done on this task. Default false.

Duration

Some options above have to be filled with a duration notation. Durations are expressed in ISO 8601 Durations, here are some examples:

namedescription
PT0.250S250 milliseconds delay
PT2S2 seconds delay
PT1M1 minute delay
PT3.5H3 hours and a half delay

Retry types

constant

This establishes constant retry times: if the interval property is set to 10 minutes, it retries every 10 minutes.

nametypedescription
intervalDurationDuration between each retry.

exponential

This establishes retry behavior that waits longer between each retry e.g. 1s, 5s, 15s, ...

nametypedescription
intervalDurationDuration between each retry.
maxIntervalDurationMax Duration between each retry.
delayFactorDoubleMultiplier for the interval on between retry, default is 2. For example, with an interval of 30s and a delay factor of 2, retry will append at 30s, 1m30, 3m30, ...

random

This establishes retries with a random delay within minimum and maximum limits.

nametypedescription
minIntervalDurationMinimal duration between each retry.
maxIntervalDurationMaximum duration between each retry.

Configuring retries globally

You can also configure retries globally for all tasks in a flow by using the plugins configuration:

yaml
kestra:
  plugins:
    configurations:
      - type: io.kestra
        values:
          retry:
            type: constant
            maxAttempt: 3
            interval: PT30S

This configuration will apply a constant retry with a maximum of 3 attempts every 30 seconds to all tasks across all flows.


Retry vs. Restart vs. Replay

Automatic vs. manual

Retries ensure that failed task runs are automatically rerun within the same Execution. Apart from retries, defined within your flow code, you can also manually rerun the flow from the Flow Execution page in the UI using the Restart or Replay buttons.

replay_restart.png

Restart vs. Replay

While Restart will rerun failed tasks within the current Execution (i.e., without creating a new execution), a Replay would result in a completely new run with a different Execution ID than the initial run.

replay.png

When you replay an Execution, a new execution gets created for the same flow. However, you can still track which Execution triggered this new run thanks to the Original Execution field:

original_execution.png

Replay can be executed from any task, even if that task executed successfully. But note that when you trigger a replay from a specific failed task, it will still result in a new Execution running all tasks downstream of your chosen start task:

replay_task.png

When you want to rerun only failed tasks, use Restart.

Summary: Retries vs. Restart vs. Replay

The table below summarizes the differences between a retry, restart and replay.

ConceptFlow or task levelAutomatic or manualDoes it create a new execution?
RetryTask levelAutomaticNo, it only reruns a given task within the same Execution. Each retry results in a new attempt number, allowing you to see how many times a given task run was retried.
RestartFlow levelManualNo, it only reruns all failed tasks within the same Execution. It's meant to handle unanticipated, transient failures. The UI shows a new attempt number for all task runs that were restarted.
ReplayEither flow or task levelManualYes. You can pick an arbitrary step from which a new execution should be triggered. If you select a task in the middle that needs outputs from a previous task, its output is retrieved from cache.