Workflow Timeout Template

The Workflow Timeout template demonstrates how BindAI can stop a workflow when its total execution time exceeds a configured limit. The timeout is enforced by the workflow executor. Before each node is executed, the executor compares the elapsed time since the workflow started with the configured timeout duration. If the limit has been exceeded, the workflow fails with the error "Workflow timeout.".

Purpose

This template demonstrates how to:

configure a workflow timeout
limit total workflow execution time
detect workflows that run longer than allowed
fail timed-out workflows predictably
protect workflows from excessive execution time

Timeouts are especially useful for workflows that depend on external services or may otherwise run for an unexpectedly long time.

Workflow Structure

A timeout does not change the normal workflow structure.

Start

↓

Operation

↓

Next Node

↓

End

The executor monitors elapsed workflow time while progressing through the nodes.

Timeout Policy

A workflow timeout is configured using a TimeoutPolicy. The policy defines the maximum number of seconds allowed for workflow execution. For example:

TimeoutPolicy(
    seconds=30,
)

The timeout is stored on the workflow execution context:

context.timeout_policy = TimeoutPolicy(
    seconds=30,
)

How Timeout Detection Works

The executor checks the timeout before executing each node. Conceptually:

Workflow Started

↓

Check Elapsed Time

↓

Within Limit?
      ↙       ↘
    Yes        No
     ↓          ↓
Execute Node   Fail Workflow
     ↓
Next Node
     ↓
Check Again

The elapsed time is calculated from the workflow context’s started_at timestamp. The executor compares:

elapsed = datetime.now(UTC) - context.started_at

against the configured timeout:

timedelta(
    seconds=policy.seconds,
)

Timeout Trigger

If the elapsed execution time exceeds the configured limit, the executor immediately enters the workflow failure path. Conceptually:

Execute Workflow

↓

Timeout Check

↓

Limit Exceeded

↓

Workflow Failed

↓

"Workflow timeout."

The timeout error is generated by the executor:

self._failure(
    instance,
    "Workflow timeout.",
)

Timeout Failure Behavior

A timeout is treated as a workflow failure. When _failure() is called, BindAI:

executes registered compensation handlers
records the timeout error
marks the workflow as completed
records the finish time
emits a workflow.failed event
persists the workflow state
stores failed execution history
returns an unsuccessful WorkflowResult

The recorded error is:

Workflow timeout.

The resulting workflow execution is therefore unsuccessful.

Timeout and Node Execution

Timeout checking occurs between node executions. For example:

Node A

↓

Timeout Check

↓

Node B

↓

Timeout Check

↓

Node C

This means the timeout mechanism does not continuously interrupt a node that is already executing. If a node takes longer than the configured timeout while it is running, the executor detects the exceeded limit when it reaches the next timeout check. For example:

Start

↓

Long-running Node

↓

Timeout Check

↓

Timeout Detected

↓

Workflow Failed

This distinction is important when designing workflows containing long-running operations.

Timeout Duration

The timeout duration is measured from the workflow’s started_at timestamp. The executor does not reset the timeout after each node. For example, with:

TimeoutPolicy(
    seconds=30,
)

the workflow has approximately 30 seconds of total execution time from its recorded start time. The timeout therefore applies to the workflow execution as a whole rather than providing a separate 30-second allowance for every node.

Successful Execution

If the workflow finishes before the timeout limit, execution completes normally.

Workflow Started

↓

Node A

↓

Node B

↓

Node C

↓

Workflow Completed

The timeout policy is never triggered. The executor records a successful completion and returns:

WorkflowResult(
    success=True,
    output=context.variables,
)

Timed-Out Execution

If the workflow exceeds the configured duration before the next node execution, the workflow fails.

Workflow Started

↓

Node A

↓

Node B

↓

Timeout Check

↓

Timeout Exceeded

↓

Workflow Failed

The final result is unsuccessful and contains the timeout error.

Workflow Events

A successful workflow emits a completion event:

workflow.completed

A timed-out workflow follows the failure path and emits:

workflow.failed

The failure event contains the workflow and execution identifiers together with the timestamp at which the timeout failure was recorded.

Execution History

Timed-out workflows are stored as failed executions in the workflow history. The history records:

success = False
error = "Workflow timeout."

This makes timeout failures available for monitoring and troubleshooting.

Persistence

The workflow state is persisted when the timeout failure occurs. The executor saves the workflow instance before returning the failure result. This allows the failed execution state to remain available to the rest of the workflow infrastructure.

Timeout and Retry

Timeouts and retries solve different problems.

Timeout	Retry
Limits total workflow execution time	Repeats failed node execution
Based on elapsed time	Based on node execution failure
Fails the workflow when exceeded	Retries until success or attempt limit
Protects against excessive workflow duration	Helps recover from transient failures

A retry policy does not make the timeout disappear. The workflow timeout is checked independently by the executor before node execution.

Timeout and Loops

Timeouts are particularly useful for workflows containing loops. A loop may intentionally execute many iterations:

Loop

↓

Process Item

↓

Update State

↓

Loop

If the loop takes too long overall, the workflow timeout provides an additional execution limit:

Loop

↓

Process

↓

Loop

↓

Timeout Check

↓

Workflow Failed

This provides protection against unexpectedly long or incorrectly terminating workflows.

Timeout and Parallel Execution

Timeouts also apply to workflows containing parallel branches. For example:

Parallel

↙          ↘

Branch A   Branch B

↓          ↓

Join

↓

Continue

The workflow still uses its shared execution start time when checking the timeout. A timeout therefore limits the overall workflow execution rather than assigning an independent timeout duration to each branch.

Long-Running Operations

Timeouts are useful for workflows that interact with:

AI providers
external APIs
databases
document processing systems
cloud services
network operations
external integrations

However, remember that timeout detection occurs between node executions. If an individual node blocks for a long period, the workflow executor cannot detect the timeout until control returns to the executor.

Choosing a Timeout

Timeout values should reflect the expected total duration of the workflow. For example:

Workflow Type	Example Timeout
Simple workflow	10–30 seconds
AI workflow	30–120 seconds
Document processing	Several minutes
Large batch workflow	Based on expected workload

These values are examples rather than framework-enforced defaults. Choose a timeout based on the actual workload and operational requirements.

Best Practices

Set a realistic timeout for the entire workflow.
Remember that the timeout is measured from started_at.
Do not assume the timeout interrupts an already-running node.
Use timeouts as protection against unexpectedly long workflows.
Combine timeouts with retry policies when appropriate.
Monitor workflow.failed events for timeout failures.
Inspect execution history for repeated timeout errors.
Make loop termination conditions explicit.
Design long-running operations with the executor’s node-level timeout checking behavior in mind.

Summary

The Workflow Timeout template demonstrates how BindAI limits the total execution time of a workflow. A TimeoutPolicy specifies the maximum duration in seconds. During execution, the WorkflowExecutor checks the elapsed time before each node. If the configured limit has been exceeded, the executor fails the workflow with:

Workflow timeout.

The normal failure lifecycle then records the error, emits a workflow.failed event, persists the execution state, stores failed history, and returns an unsuccessful WorkflowResult. Timeouts therefore provide a predictable safety mechanism for preventing workflows from continuing indefinitely while remaining compatible with loops, retries, parallel execution, and other workflow features.

Getting Started

Core

Tools

Memory

Knowledge

Connections

Automation

Workflows

Projects

Templates

Roadmap

API Reference

08.7 workflow timeout

Workflow Timeout Template

Purpose

Workflow Structure

Timeout Policy

How Timeout Detection Works

Timeout Trigger

Timeout Failure Behavior

Timeout and Node Execution

Timeout Duration

Successful Execution

Timed-Out Execution

Workflow Events

Execution History

Persistence

Timeout and Retry

Timeout and Loops

Timeout and Parallel Execution

Long-Running Operations

Choosing a Timeout

Best Practices

Summary

​Workflow Timeout Template

​Purpose

​Workflow Structure

​Timeout Policy

​How Timeout Detection Works

​Timeout Trigger

​Timeout Failure Behavior

​Timeout and Node Execution

​Timeout Duration

​Successful Execution

​Timed-Out Execution

​Workflow Events

​Execution History

​Persistence

​Timeout and Retry

​Timeout and Loops

​Timeout and Parallel Execution

​Long-Running Operations

​Choosing a Timeout

​Best Practices

​Summary

Workflow Timeout Template

Purpose

Workflow Structure

Timeout Policy

How Timeout Detection Works

Timeout Trigger

Timeout Failure Behavior

Timeout and Node Execution

Timeout Duration

Successful Execution

Timed-Out Execution

Workflow Events

Execution History

Persistence

Timeout and Retry

Timeout and Loops

Timeout and Parallel Execution

Long-Running Operations

Choosing a Timeout

Best Practices

Summary