Retry a failing task up to 4 times (5 attempts total)

Transient failures are a fact of life in data and infrastructure pipelines: a flaky API, a brief network blip, or a service that is momentarily unavailable. This blueprint shows how to make a task self-heal by attaching a declarative retry policy to it, so Kestra automatically re-runs the task until it succeeds instead of failing the whole flow. It demonstrates a constant retry strategy with a fixed interval, a maximum attempt count, and a maximum total duration.

How it works

The flow contains a single shell task, fail_4_times, of type io.kestra.plugin.scripts.shell.Commands, executed with the io.kestra.plugin.core.runner.Process task runner. The command inspects {{ taskrun.attemptsCount }} and intentionally exits with a failure code until the 4th retry, then exits successfully on the 5th attempt. A retry block of type: constant drives the behavior: interval: PT0.25S waits a quarter second between tries, maxAttempt: 5 caps the number of attempts, maxDuration: PT1M bounds the total retry window to one minute, and warningOnRetry: false keeps retried executions from being flagged as warnings.

The flow also defines an errors branch, will_never_happen, of type io.kestra.plugin.core.debug.Return. Because the retries resolve the failure before the attempts are exhausted, this error handler is never triggered, illustrating that a successful retry keeps the execution green.

What you get

• A working, copy-paste example of a declarative retry policy
• Automatic recovery from transient task failures without manual reruns
• Bounded retries via maxAttempt and maxDuration so flows fail fast when truly broken
• A pattern for inspecting {{ taskrun.attemptsCount }} to reason about retry behavior

Who it's for

• Data engineers building resilient pipelines against flaky upstream systems
• Platform and DevOps teams that want self-healing automation
• Anyone learning how Kestra models retries and error handling

Why orchestrate this with Kestra

Retries in Kestra are declarative and live next to the task in plain YAML, with no custom wrapper scripts or sleep loops. You get strategy choices (constant, exponential, random), attempt and duration caps, lineage across every attempt in the execution UI, and full control over whether retries surface as warnings. Combined with event triggers, error branches, and visible execution history, this fills the gap left by tools whose own schedulers can only rerun an entire job rather than retry a single failing step with a bounded backoff policy.

Prerequisites

• A running Kestra instance
• A shell environment available to the Process task runner (no external services required)

Secrets

This flow references no secrets and needs no credentials to run.

Quick start

1. Add this flow to your Kestra instance.
2. Execute it from the UI.
3. Open the execution and watch fail_4_times retry every 0.25 seconds.
4. Confirm the task turns green on its 5th attempt and the flow succeeds.

How to extend

• Swap the constant strategy for exponential or random to space out retries.
• Tune maxAttempt and maxDuration to match your tolerance for transient errors.
• Replace the shell command with a real task (an HTTP call, a database query) to protect against actual flaky dependencies.
• Set warningOnRetry: true to flag executions that needed retries for observability.

Links

• Plugin docs: https://kestra.io/plugins/plugin-scripts