Skip to content

Wait ​

Wait for time, file state, or HTTP readiness without wrapping polling loops in shell scripts.

Actions ​

ActionUse forRequired fields
wait.durationWait for a fixed durationduration
wait.untilWait until a timestamp or time of dayuntil
wait.filePoll for a file path to exist or disappearpath
wait.httpPoll an HTTP endpoint until it returns a statusurl

All duration fields use Go duration strings such as 500ms, 30s, 5m, or 1h.

Wait for a Duration ​

yaml
steps:
  - id: give_service_time
    action: wait.duration
    with:
      duration: 30s

Wait Until a Time ​

until is an RFC3339 timestamp or an HH:MM[:SS] time of day.

yaml
steps:
  - id: maintenance_window
    action: wait.until
    with:
      until: "2030-01-02T03:04:05Z"  # Example future timestamp

A time of day resolves on the run's logical day: the date of context.run.scheduled_at for scheduled runs, which retries keep, otherwise the date the current attempt started. It is read in timezone when set, otherwise in the configured tz. It never rolls over to the next day.

offset shifts the deadline by a signed duration, so release gates can be written relative to one release time:

yaml
steps:
  - id: gate_3h
    action: wait.until
    with:
      until: "16:30"
      offset: -3h
      timezone: Europe/London
      if_past: fail

  - id: gate_1h
    depends: gate_3h
    action: wait.until
    with:
      until: "16:30"
      offset: -1h
      timezone: Europe/London

Past Deadlines ​

if_past decides what happens when the deadline, after offset, has already passed when the step starts:

if_pastDeadline already passed
continue (default)The step succeeds immediately.
failThe step fails.
windowThe step succeeds if the deadline passed no more than window ago, and fails otherwise.
yaml
steps:
  - id: start_window
    action: wait.until
    with:
      until: "11:30"
      if_past: window
      window: 1h

This step waits until 11:30, starts immediately between 11:30 and 12:30, and fails after 12:30.

Daylight Saving Time ​

A time of day that a daylight-saving change skips is read with the UTC offset before the change, so 02:30 on the night New York springs forward resolves to 03:30 EDT. A time that occurs twice resolves to its first occurrence.

The step writes its resolved deadline to stderr, such as wait: deadline 2030-01-02T16:30:00Z (zone GMT, if_past fail).

Wait for a File ​

By default, wait.file waits for the path to exist. Use state: missing to wait until it disappears.

yaml
steps:
  - id: wait_for_ready_file
    action: wait.file
    with:
      path: ./ready.flag
      poll_interval: 2s
yaml
steps:
  - id: wait_for_lock_release
    action: wait.file
    with:
      path: ./deploy.lock
      state: missing
      poll_interval: 5s

Relative paths resolve from the step working directory.

Wait for HTTP Readiness ​

wait.http retries until the response status matches status. The default method is GET, and the default status is 200.

yaml
steps:
  - id: wait_for_api
    action: wait.http
    with:
      url: https://api.example.com/health
      status: 204
      poll_interval: 3s
      request_timeout: 10s

Headers and request bodies are supported:

yaml
steps:
  - id: wait_for_search
    action: wait.http
    with:
      method: POST
      url: https://api.example.com/search/ready
      status: 200
      headers:
        Authorization: "Bearer ${env.API_TOKEN}"
        Content-Type: application/json
      body: '{"index":"customers"}'

Network errors, connection refusals, and non-matching statuses are treated as "not ready" and retried until the step context is canceled or the DAG step times out.

Configuration ​

FieldTypeDefaultUsed byDescription
durationstringnonewait.durationFixed duration to wait.
untilstringnonewait.untilRFC3339 timestamp or HH:MM[:SS] time of day.
offsetstringnonewait.untilSigned duration added to the deadline, such as -3h.
timezonestringconfig tzwait.untilIANA timezone for a time of day. Ignored for RFC3339 timestamps.
if_paststringcontinuewait.untilcontinue, fail, or window.
windowstringnonewait.untilHow long after the deadline still counts as on time. Required with if_past: window.
pathstringnonewait.fileFile or directory path.
statestringexistswait.fileexists or missing.
urlstringnonewait.httpAbsolute HTTP URL.
methodstringGETwait.httpHTTP method.
statusinteger or string200wait.httpExpected HTTP status code.
headersmapnonewait.httpHTTP request headers.
bodystringnonewait.httpHTTP request body.
poll_intervalstring1swait.file, wait.httpInterval between readiness checks.
request_timeoutstring10swait.httpPer-request timeout.

offset, timezone, if_past, and window are only valid on wait.until. Use the step-level timeout_sec field to set an overall maximum wait time.

Value References ​

Every field accepts value references, such as ${params.deadline}, ${env.BASE_URL}/health, or a previous step's output. References resolve when the step starts.

A literal value is validated when the DAG is built. A value that contains a ${...} or $VAR reference is validated after it resolves, when the step starts, so a bad resolved value fails the step instead of the DAG build. If the reference did not resolve, the error says so. Escape a literal $ as \$.

yaml
params:
  - deadline: "2030-01-02T03:04:05Z"

steps:
  - id: wait_for_deadline
    action: wait.until
    with:
      until: ${params.deadline}

Dagu is open source under the GNU General Public License v3.0.