Timeouts

Timeout parameters define the maximum duration for workflow execution, activity execution, and task processing in Temporal. Configure these parameters when starting workflows or invoking activities to detect failures and bound execution windows.

Workflow timeouts

Workflow timeouts control the duration of workflow execution and task processing. Configure these parameters when starting a workflow with client.execute_workflow().

execution_timeouttimedelta

Optional

Maximum duration for the entire workflow execution across all runs. If exceeded, the workflow times out and fails. Use this to set an absolute deadline for workflow completion regardless of retries or Continue-As-New operations.

run_timeouttimedelta

Optional

Maximum duration for a single workflow run between Continue-As-New operations. Prevents a single run from growing unbounded in size or duration. Use this to enforce periodic state checkpointing through Continue-As-New.

task_timeouttimedelta

Optional

Maximum time for a worker to process a workflow task (decision task). Surfaces stuck workers or excessively long decision logic. Typically set to 10-30 seconds.

Usage example

This example starts a workflow with all three timeout parameters configured. The workflow fails if it runs longer than 2 seconds total (execution_timeout), if a single run exceeds 2 seconds (run_timeout), or if the worker takes more than 2 seconds to process a workflow task (task_timeout).

from datetime import timedelta

result = await client.execute_workflow(
    YourWorkflow.run,
    "your timeout argument",
    id="your-workflow-id",
    task_queue="your-task-queue",
    execution_timeout=timedelta(seconds=2),
    run_timeout=timedelta(seconds=2),
    task_timeout=timedelta(seconds=2),
)

Activity timeouts

Activity timeouts control the duration of activity execution, queuing, and overall completion. Configure these parameters when invoking activities from workflows with workflow.execute_activity().

schedule_to_start_timeouttimedelta

Optional

Maximum time from activity scheduling until a worker picks it up. Detects worker capacity issues or unavailability. Use this to surface worker pool pressure or infrastructure problems.

start_to_close_timeouttimedelta

Optional

Maximum time the activity code can run after starting. Detects stuck or excessively long-running execution. Use this to bound the runtime of external calls and operations.

schedule_to_close_timeouttimedelta

Optional

Overall deadline from scheduling to completion, including queueing and execution. Bounds total wall-clock time. Use this when you need a single upper bound on total activity duration.

Usage example

This example invokes an activity with all three timeout parameters configured. The activity fails if no worker picks it up within 10 seconds (schedule_to_start_timeout), if execution takes longer than 30 seconds after starting (start_to_close_timeout), or if the total time from scheduling to completion exceeds 2 minutes (schedule_to_close_timeout).

from datetime import timedelta
from temporalio import workflow

@workflow.defn
class MyWorkflow:
    @workflow.run
    async def run(self):
        result = await workflow.execute_activity(
            my_activity,
            start_to_close_timeout=timedelta(seconds=30),
            schedule_to_start_timeout=timedelta(seconds=10),
            schedule_to_close_timeout=timedelta(minutes=2),
        )
        return result

Heartbeat timeout

Heartbeat timeout controls the maximum time between heartbeat signals for long-running activities. Configure this parameter when invoking activities that implement heartbeat signals.

heartbeat_timeouttimedelta

Optional

Maximum time between heartbeat signals for long-running activities. If the Temporal server doesn't receive a heartbeat within this timeout, the activity times out and becomes eligible for retry. Use this for iterative or chunked work where activities can signal progress.

Usage example

This example invokes a long-running activity with heartbeat timeout configured. The activity must send heartbeat signals at least every 15 seconds. If the Temporal server doesn't receive a heartbeat within this timeout, the activity fails and becomes eligible for retry according to the retry policy.

from datetime import timedelta
from temporalio import workflow

result = await workflow.execute_activity(
    my_activity,
    heartbeat_timeout=timedelta(seconds=15),
    start_to_close_timeout=timedelta(minutes=5),
)

See also

• Retry strategies: Understand the concepts behind retry strategies and timeouts