Error Handling

Every workflow step decides what happens when it fails. By default a failure stops the whole run — but you can also continue past it or retry. The simplest failing pipeline: on_error="stop" (the Task default) aborts the run the moment a step raises.

from praisonaiagents import Task, AgentFlow, WorkflowContext, StepResult

def boom(ctx: WorkflowContext) -> StepResult:
    raise RuntimeError("boom")

def after(ctx: WorkflowContext) -> StepResult:
    return StepResult(output="this never runs")

workflow = AgentFlow(steps=[
    Task(name="boom", handler=boom, max_retries=0),
    Task(name="after", handler=after),
])
result = workflow.start("go")

print(result["status"])  # "failed" — after() never ran

How it Works

A step raises, on_error is consulted, and the run either aborts or keeps going — but the final status reflects the failure either way.

Which mode when?

Pick the mode that matches how much a single failure should affect the run.

Stop → data integrity matters; one failure means the whole run is wrong.
Continue → batch processing; partial results are useful.
Retry → transient failures like network blips or rate limits.

`on_error` Options

Value	Behavior
`"stop"` (default)	Failing step aborts the whole workflow, `status="failed"`. Downstream steps do not run. Exception is not fed to the next step.
`"continue"`	Failing step is recorded as `failed`; the workflow keeps going. Final `status="failed"` if any step failed. Exception is not fed to the next step.
`"retry"`	Same as `stop`, but only after `max_retries` are exhausted.

Retry Configuration

Set max_retries on flaky steps. Retries use exponential backoff of 2 ** (attempt - 1) seconds between attempts.

from praisonaiagents import Task, AgentFlow

class TransientError(Exception):
    is_retryable = True   # honoured by the retry machinery

flow = AgentFlow(steps=[
    Task(name="fetch", handler=fetch_data, max_retries=3, on_error="retry"),
])
flow.start("go")

max_retries — how many extra attempts before the step is considered failed (default 3).
is_retryable — set False on your exception class to short-circuit retries for known non-retryable failures.
Backoff between attempts is 2 ** (attempt - 1) seconds.

Guardrail Failures

A guardrail that never validates after exhausting its retries is treated like an exception — it surfaces as step_error and follows the same on_error rules. See Guardrails for validator configuration.

Errors in Nested Patterns

As of PR #4194, the same rules apply inside every nested pattern. A stopping step propagates out of the pattern and aborts the enclosing workflow.

In loop

Sequential and parallel iterations both honour on_error. A stopping iteration halts the enclosing workflow, not just the loop.

from praisonaiagents import Task, AgentFlow, WorkflowContext, StepResult, loop

def boom(ctx: WorkflowContext) -> StepResult:
    raise RuntimeError("boom")

def after(ctx: WorkflowContext) -> StepResult:
    return StepResult(output="this never runs")

workflow = AgentFlow(
    steps=[
        loop(steps=[Task(name="boom", handler=boom, max_retries=0)], over="items"),
        Task(name="after", handler=after),
    ],
    variables={"items": ["only"]},
)
result = workflow.start("go")

print(result["status"])                                     # "failed"
print(any(s["step"] == "after" for s in result["steps"]))   # False

In parallel

The three on_failure modes now behave differently (see the table below).

from praisonaiagents import Task, AgentFlow, WorkflowContext, StepResult, parallel, loop

def boom(ctx: WorkflowContext) -> StepResult:
    raise RuntimeError("boom")

workflow = AgentFlow(steps=[
    parallel(
        [loop(steps=[Task(name="boom", handler=boom, max_retries=0)], over="items")],
        on_failure="fail_fast",
    )
], variables={"items": ["only"]})

result = workflow.start("go")
print(result["status"])  # "failed"

In when / if_

A stopping step inside a conditional branch stops the workflow, not just the branch.

In route

A stopping step inside the matched route stops the workflow.

In repeat

A stopping iteration ends the repeat loop and the workflow.

`on_error="continue"` keeps running

from praisonaiagents import Task, AgentFlow, WorkflowContext, StepResult, loop

def boom(ctx: WorkflowContext) -> StepResult:
    raise RuntimeError("boom")

workflow = AgentFlow(
    steps=[loop(
        steps=[Task(name="boom", handler=boom, on_error="continue", max_retries=0)],
        over="items",
    )],
    variables={"items": ["a", "b", "c"]},
)
result = workflow.start("go")

print(result["status"])  # "failed" — the run keeps going but reports failure

The exception text is never fed to the next step. A downstream step receives the last successful output (or the initial input), never "Error: boom".

Reading the Result

Inspect result["status"] and each step’s error field to find what failed.

result = workflow.start("go")
if result["status"] == "failed":
    for step in result["steps"]:
        if step.get("error"):
            print(f"{step['step']} failed: {step['error']}")

You can also read workflow.step_statuses for a per-step status map after the run.

`parallel(on_failure=...)` Modes

Mode	When any branch fails
`fail_fast`	Cancel remaining branches, raise `WorkflowStepError` immediately.
`fail_all`	Let all branches finish, then raise with the collected errors.
`partial_ok`	Record the failure, keep the other branches, return combined output.

In every mode the whole run is marked failed. With partial_ok, the failing branch is recorded as {"output": None, "error": str(e)} — the exception text is not folded into the branch output.

Behavior Change

Runs that previously reported completed while containing a failed step now correctly report failed. If you built on the old (broken) behaviour you may see “new” failures appear — this is intentional, the old behaviour was silent data corruption. See PR #4194.

Best Practices

Default to stop

Use on_error="stop" unless you have a concrete reason to continue. It keeps a failed run from producing partially-correct output.

Handle per-item errors inside loops

Prefer per-item try/except inside your handler when you want fine-grained control inside loop(parallel=True) — convert an expected failure into a valid StepResult the rest of the run can consume.

Retry flaky steps, don't loop them

Set max_retries on steps that hit the network or LLM rate limits rather than wrapping them in repeat.

Check status before reusing output

Never feed a previous step’s output to a downstream step without checking result["status"] first.

Workflows

Build multi-step workflows with AgentFlow

Nested Workflows

Combine loops, parallel, and routing patterns

Guardrails

Validate step output and retry on failed checks

Workflow Manager API

API reference for step statuses and error handling

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

How it Works

Which mode when?

`on_error` Options

Retry Configuration

Guardrail Failures

Errors in Nested Patterns

`on_error="continue"` keeps running

Reading the Result

`parallel(on_failure=...)` Modes

Behavior Change

Best Practices

Workflows

Nested Workflows

Guardrails

Workflow Manager API

​How it Works

​Which mode when?

​on_error Options

​Retry Configuration

​Guardrail Failures

​Errors in Nested Patterns

​on_error="continue" keeps running

​Reading the Result

​parallel(on_failure=...) Modes

​Behavior Change

​Best Practices

​Related

Workflows

Nested Workflows

Guardrails

Workflow Manager API

How it Works

Which mode when?

`on_error` Options

Retry Configuration

Guardrail Failures

Errors in Nested Patterns

`on_error="continue"` keeps running

Reading the Result

`parallel(on_failure=...)` Modes

Behavior Change

Best Practices

Related