Timeouts

Timeouts specify the maximum execution time for jobs and steps. If execution exceeds the timeout, the job or step is terminated.

Schema

Timeouts are defined as timeout?: time.Duration at job and step levels.

See Schema Reference for complete schema definitions.

Duration Format

Timeouts use Go's standard duration string format. A duration string is a sequence of decimal numbers, each with optional fraction and unit suffix.

Supported Units

Unit	Description
ns	Nanoseconds
us or µs	Microseconds
ms	Milliseconds
s	Seconds
m	Minutes
h	Hours

Format Rules

• Durations can combine multiple units: "1h30m", "2h45m30s".
• Units must be specified from larger to smaller: "1h30m" (correct), "30m1h" (incorrect).
• Decimal values are allowed: "1.5h", "2.5m".
• No spaces between value and unit: "5m" (correct), "5 m" (incorrect).
• Values must be positive (zero and negative durations are invalid and cause validation errors).
• Maximum 24 hours. Any timeout greater than 24h is rejected at validation time. This cap applies to both job-level and step-level timeouts.

Valid Examples

timeout: "30s"      # 30 seconds
timeout: "5m"       # 5 minutes
timeout: "1h"       # 1 hour
timeout: "1h30m"    # 1 hour 30 minutes
timeout: "1.5h"     # 1.5 hours (90 minutes)

Invalid Examples

timeout: "30"        # ❌ Missing unit
timeout: "1 h"       # ❌ Space between value and unit
timeout: "30m1h"     # ❌ Wrong order (minutes before hours)
timeout: "25h"       # ❌ Exceeds the 24h maximum

Scope Levels

Timeouts can be configured at two levels:

Job-Level Timeout

Maximum execution time for the entire job, including all steps.

Location: timeout field in job definition

Behavior: If any step in the job causes the total time to exceed the job timeout, the job is terminated.

Example:

jobs:
  train:
    name: Train Model
    timeout: "2h"
    steps:
      - name: Load dataset
      - name: Preprocess data
      - name: Train model

Step-Level Timeout

Maximum execution time for an individual step.

Location: timeout field in step definition

Behavior: If the step exceeds its timeout, only that step is terminated.

Example:

steps:
  - name: Evaluate model
    timeout: "10m"
  - name: Deploy model
    timeout: "5m"

Timeout Precedence and Behavior

Job and Step Timeouts Together

When both job and step timeouts are specified:

• Step timeout applies to individual step execution.
• Job timeout applies to total job execution time.
• Whichever limit is reached first will terminate execution.

Example:

jobs:
  train:
    name: Train Models
    timeout: "3h"   # Job must complete in 3 hours
    steps:
      - name: Train baseline model
        timeout: "1h"   # This step must complete in 1 hour
      - name: Train advanced model
        timeout: "2h"   # This step must complete in 2 hours

In this example:

• Each step has a maximum of 1h and 2h respectively
• The entire job (both steps combined) must complete within 3 hours
• If step 1 takes 55m and step 2 takes 2h10m, the job times out (total 3h5m exceeds job timeout)

Default Behavior

The job timeout bounds the whole job. A step timeout, if set, is a tighter cap on a single step within that budget.

When no timeout is specified:

• Job: defaults to 6h (configured via the orchestrator's default-job-timeout flag). Set the flag to 0 to disable the default and let jobs run unbounded.
• Step: has no separate default. A step with no explicit timeout is bounded only by the job's remaining budget. A per-step timeout is an optional, tighter cap on that individual step.

It's recommended to specify timeouts explicitly for long-running operations so the limit is part of the workflow definition rather than dependent on cluster configuration.

---

Feedback

• Submit and view feedback for this page
• Send feedback about H2O Workflows to cloud-feedback@h2o.ai