Skip to main content

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​

UnitDescription
nsNanoseconds
us or µsMicroseconds
msMilliseconds
sSeconds
mMinutes
hHours

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).

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)

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​

When timeout is not specified:

  • System default timeout is used
  • Default values are determined by the workflow execution engine
  • It's recommended to specify timeouts for long-running operations
Feedback