Workflow Timeout Template

The Workflow Timeout template demonstrates how BindAI’s workflow executor detects when a workflow has exceeded its configured elapsed-time limit. Timeout checking is implemented in the workflow executor. Before processing a node, the executor compares the elapsed time since the workflow started with the configured TimeoutPolicy. If the elapsed time exceeds the configured limit, the executor enters the normal workflow failure path with the error:

Workflow timeout.

The current implementation is a workflow-level elapsed-time check. It does not forcibly interrupt a node that is already executing, and it does not guarantee that a workflow will stop exactly when the configured duration expires.

Purpose

This template demonstrates how to:

Configure a workflow timeout policy
Limit the elapsed time allowed for a workflow
Detect workflows that exceed their configured duration at executor check points
Handle timeout detection through normal workflow failure handling
Protect against workflows that take unexpectedly long to complete

Timeouts can be useful for workflows that depend on external services, contain loops, or perform operations that may take longer than expected.

Workflow Structure

A timeout does not introduce additional workflow nodes. The normal workflow structure remains:

Node A
   |
   v
Node B
   |
   v
Node C
   |
   v
Completed

The executor checks elapsed workflow time as it progresses through its execution loop. Timeout detection therefore depends on the executor reaching a timeout check.

TimeoutPolicy

Timeout configuration is represented by TimeoutPolicy:

from bindai_workflow.timeout import TimeoutPolicy

policy = TimeoutPolicy(
    seconds=30,
)

The policy contains two fields:

Field	Default	Current role
`seconds`	Required	Maximum elapsed time used by the executor’s timeout check
`fail_workflow`	`True`	Configuration field that the current executor does not consult

A policy can be assigned to the workflow execution context:

context.timeout_policy = TimeoutPolicy(
    seconds=30,
)

This assignment illustrates how the policy is configured on a context. The workflow must actually be executed with that context and policy for the executor to use it.

Timeout Policy Defaults

TimeoutPolicy is a dataclass. For example:

TimeoutPolicy(
    seconds=30,
)

creates a policy with these values:

seconds=30
fail_workflow=True

The fail_workflow field currently does not change executor behavior. When the executor detects that the timeout has been exceeded, it enters workflow failure handling regardless of the value of fail_workflow.

How Timeout Detection Works

The workflow executor checks the timeout during its main execution loop, before processing a node. Conceptually:

Workflow Started
       |
       v
Check Elapsed Time
       |
       +---- Within Limit ----> Process Node
       |                            |
       |                            v
       |                       Next Check
       |                            |
       +----------------------------+
       |
       +---- Limit Exceeded ----> Fail Workflow

The elapsed time is calculated from the workflow context’s started_at timestamp. Conceptually, the calculation is:

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

The executor compares the elapsed duration against the configured policy:

timedelta(seconds=policy.seconds)

The timeout condition is triggered when the elapsed time is greater than the configured duration.

Timeout Trigger

If the elapsed time exceeds the configured duration when the executor checks it, the executor enters its failure path. The failure is generated using the error message:

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

The workflow then follows the normal failure lifecycle and returns an unsuccessful WorkflowResult. The timeout mechanism does not run as a separate background timer.

Timeout Failure Behavior

A timeout is handled as a normal workflow failure. The failure path performs the workflow executor’s configured failure handling, which includes:

Executing registered compensation callbacks.
Recording the timeout error.
Marking the workflow context as completed.
Recording the finish time.
Emitting a workflow.failed event.
Persisting the workflow instance.
Storing failed workflow history.
Returning an unsuccessful WorkflowResult.

The error recorded for the timeout is:

Workflow timeout.

These are the normal failure-handling operations, not a separate timeout-specific lifecycle.

Timeout Checking and Node Execution

Timeout detection occurs in the executor’s workflow loop before the next node is processed. For example:

Node A
   |
   v
Timeout Check
   |
   v
Node B
   |
   v
Timeout Check
   |
   v
Node C

The timeout mechanism does not continuously interrupt a node that is already running. For example:

Workflow Started
       |
       v
Long-running Node
       |
       |  <-- node continues executing
       |
       v
Node Returns
       |
       v
Next Timeout Check
       |
       v
Timeout Detected, if limit exceeded

If a node blocks for a long time, the executor cannot perform its next timeout check until control returns from that node. Consequently, the configured duration is a threshold checked by the executor, not a hard real-time deadline that forcibly terminates execution.

Total Workflow Duration

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

TimeoutPolicy(
    seconds=30,
)

sets a threshold of 30 seconds of elapsed workflow time from the recorded start time. It does not give every node a new 30-second allowance. The actual time at which a timeout is detected can be later than the configured threshold if a node is still executing when the threshold is crossed.

Successful Execution

If the workflow completes without a timeout being detected, execution proceeds through the normal success path.

Workflow Started
       |
       v
Node A
       |
       v
Node B
       |
       v
Node C
       |
       v
Workflow Completed

The executor records successful completion and returns a successful result, conceptually represented as:

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

The precise result depends on the workflow’s execution state and output.

Timed-Out Execution

If the workflow has exceeded its timeout when the executor performs its next timeout check, the failure path is entered:

Workflow Started
       |
       v
Node A
       |
       v
Node B
       |
       v
Timeout Check
       |
       v
Timeout Exceeded
       |
       v
Workflow Failed

The resulting WorkflowResult is unsuccessful and records the timeout error:

Workflow timeout.

If a node is still running when the timeout threshold passes, the failure may not be detected until that node returns and the executor reaches its next check.

Workflow Events

A successful workflow emits the normal completion event:

workflow.completed

A workflow that fails because of a detected timeout follows the failure path and emits:

workflow.failed

The failure event contains workflow and execution information provided by the existing event mechanism. There is no separate timeout-specific event in the current workflow executor.

Execution History

A timed-out workflow is recorded as a failed execution through the workflow history mechanism. The recorded result identifies the unsuccessful execution and its error, including:

success = False
error = "Workflow timeout."

The exact fields available in history depend on the workflow history representation. Failed history can help with monitoring, troubleshooting, and identifying workflows that repeatedly exceed their configured duration.

Persistence

When timeout detection enters the workflow failure path, the executor persists the workflow instance before returning the failure result. This preserves the failed execution state through the configured workflow persistence mechanism. Persistence behavior depends on the store configured for the workflow infrastructure.

`fail_workflow` Configuration

TimeoutPolicy contains this field:

fail_workflow: bool = True

For example:

TimeoutPolicy(
    seconds=30,
    fail_workflow=True,
)

However, the current WorkflowExecutor does not inspect fail_workflow. When the timeout condition is exceeded, the executor directly invokes its normal failure path:

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

Therefore, setting:

fail_workflow=False

does not currently prevent the workflow from failing after a timeout is detected. The field exists in the timeout configuration, but it is not an active execution control in the current implementation.

Timeout and Retry

Timeouts and retries address different failure scenarios.

Timeout	Retry
Checks total elapsed workflow time	Handles exceptions raised during node execution
Uses the workflow start timestamp	Uses a retry-attempt counter
Is checked by the workflow executor before processing a node	Repeats node execution after a caught exception when a retry policy allows another attempt
Enters workflow failure handling when the timeout is detected	Enters failure handling when the retry limit is reached

Conceptually:

Workflow
   |
   +---- Timeout Policy
   |
   +---- Node Operation
              |
              +---- Retry Policy

A retry does not reset the workflow’s timeout start time. The elapsed-time check continues to use the same context.started_at timestamp. Retries can increase total workflow duration, so the workflow timeout and retry policy should be configured with one another in mind. Note that the current timeout check cannot interrupt a node while it is running, even if that node is retrying after an exception.

Timeout and Loops

Timeouts can be useful for workflows containing loops. For example:

Loop
  |
  v
Process Item
  |
  v
Update State
  |
  v
Loop

The timeout provides an overall elapsed-time threshold checked as the executor progresses:

Loop
  |
  v
Process
  |
  v
Loop
  |
  v
Timeout Check
  |
  v
Workflow Failed, if limit exceeded

This can help detect workflows that take unexpectedly long to complete. The timeout does not replace the loop’s termination condition. A loop still needs an appropriate termination predicate, and a long-running node within the loop may delay timeout detection.

Timeout and Parallel Workflows

Timeout checking also uses the workflow context’s start time when a workflow contains parallel-style fan-out. For example:

             Parallel
             /      \
            v        v
        Branch A  Branch B
            \        /
             \      /
               Join
                |
                v
             Continue

The timeout is checked by the workflow executor using the workflow-level context.started_at value. The timeout policy does not define independent deadlines for individual branches. The ParallelNode itself does not implement a separate timeout mechanism. A node that blocks during parallel execution can delay the executor’s next timeout check. Do not treat the workflow timeout as a guarantee that all parallel work will be cancelled when the configured duration expires.

Long-Running Operations

Timeouts can be useful for workflows involving:

AI providers
External APIs
Databases
Document processing
Cloud services
Network operations
External integrations

However, timeout detection is executor-driven. If an individual node blocks for a long time, the executor cannot perform another timeout check until that node returns. Operations that require forcibly cancelling or interrupting long-running work need additional timeout or cancellation support at the relevant execution layer, such as the client, task, or external service integration.

Choosing a Timeout

Timeout values should reflect the expected total workflow duration, including the time spent executing nodes and any retries. The following are illustrative planning ranges, not BindAI defaults or enforced limits.

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

Choose a threshold based on actual workload characteristics and operational requirements. Account for variability in external services and remember that detection can be delayed while a node is executing.

Important Implementation Boundaries

The current timeout implementation:

Measures elapsed time from context.started_at.
Checks the timeout in the executor’s workflow loop before processing a node.
Compares elapsed time with TimeoutPolicy.seconds.
Uses a strict greater-than comparison for the configured threshold.
Enters normal workflow failure handling with "Workflow timeout." when the limit is exceeded.
Uses the existing failure lifecycle, including compensation callbacks and failure events.
Persists the workflow instance through the configured persistence mechanism.
Records failed workflow history through the configured history mechanism.

The current implementation does not:

Interrupt a node that is already executing.
Guarantee that execution stops exactly at the configured threshold.
Create a separate timeout policy for each node.
Create independently managed timeouts for parallel branches.
Reset the workflow start time after retries.
Use fail_workflow to control timeout behavior.
Emit a dedicated timeout-specific event.
Automatically cancel external operations.

Best Practices

Set a realistic timeout for the entire workflow.
Remember that elapsed time is measured from context.started_at.
Account for the combined duration of node execution and retries.
Do not assume the timeout interrupts an already-running node.
Do not assume every node receives its own timeout duration.
Do not assume fail_workflow=False disables timeout failure.
Use explicit loop termination conditions.
Consider the timeout behavior of external clients and integrations.
Combine timeouts with retry policies when appropriate.
Monitor workflow.failed events and inspect failed execution history for timeout errors.

The Workflow Timeout template relates to:

08.3 workflow-loop.md
08.4 workflow-parallel.md
08.6 workflow-retry.md
08.8 workflow-schedule.md

Timeout checking is implemented in the workflow executor, so it can apply to workflows that use these other workflow features. The timeout’s practical effectiveness still depends on where the executor can perform its checks.

Summary

The Workflow Timeout template demonstrates how BindAI detects when a workflow’s elapsed execution time exceeds a configured threshold. A TimeoutPolicy specifies the duration in seconds:

TimeoutPolicy(
    seconds=30,
)

During execution, the WorkflowExecutor checks elapsed time from context.started_at before processing a node. If the configured threshold has been exceeded at a check point, the executor enters normal workflow failure handling with:

Workflow timeout.

The failure lifecycle handles compensation callbacks, records the error, emits a workflow.failed event, persists the workflow instance, stores failed history, and returns an unsuccessful WorkflowResult. The policy also contains fail_workflow, but the current executor does not use that field. Timeouts therefore provide a workflow-level elapsed-time check, not a hard cancellation mechanism. A node that is already executing can delay timeout detection, and additional cancellation support is required when running work must be forcibly stopped.

Getting Started

Core

Tools

Memory

Knowledge

Workflows

Projects

Templates

Connections

API Reference

Automation

Roadmap

08.7 workflow timeout

Workflow Timeout Template

Purpose

Workflow Structure

TimeoutPolicy

Timeout Policy Defaults

How Timeout Detection Works

Timeout Trigger

Timeout Failure Behavior

Timeout Checking and Node Execution

Total Workflow Duration

Successful Execution

Timed-Out Execution

Workflow Events

Execution History

Persistence

`fail_workflow` Configuration

Timeout and Retry

Timeout and Loops

Timeout and Parallel Workflows

Long-Running Operations

Choosing a Timeout

Important Implementation Boundaries

Best Practices

Summary

​Workflow Timeout Template

​Purpose

​Workflow Structure

​TimeoutPolicy

​Timeout Policy Defaults

​How Timeout Detection Works

​Timeout Trigger

​Timeout Failure Behavior

​Timeout Checking and Node Execution

​Total Workflow Duration

​Successful Execution

​Timed-Out Execution

​Workflow Events

​Execution History

​Persistence

​fail_workflow Configuration

​Timeout and Retry

​Timeout and Loops

​Timeout and Parallel Workflows

​Long-Running Operations

​Choosing a Timeout

​Important Implementation Boundaries

​Best Practices

​Related Templates

​Summary

Workflow Timeout Template

Purpose

Workflow Structure

TimeoutPolicy

Timeout Policy Defaults

How Timeout Detection Works

Timeout Trigger

Timeout Failure Behavior

Timeout Checking and Node Execution

Total Workflow Duration

Successful Execution

Timed-Out Execution

Workflow Events

Execution History

Persistence

`fail_workflow` Configuration

Timeout and Retry

Timeout and Loops

Timeout and Parallel Workflows

Long-Running Operations

Choosing a Timeout

Important Implementation Boundaries

Best Practices

Related Templates

Summary