Wait for File job
- Synopsis
- Full Details
In briefA Wait for File job holds a workflow until a file appears at a path on a Universal Agent machine. It can also wait until the file is big enough, new enough and has stopped changing. It checks again on a fixed interval, and gives up after one hour. It is a built-in job type, so it needs no plugin and no connection.
WhereIn Design › Workflows, open a workflow and open the job in the Job Editor (open its context menu on the canvas › Edit Job). On the Job Definition tab, choose Wait for File as the job type, set the fields under Job Parameters, and pick a Universal Agent under Agent Assignment. The job output lists each check, so it shows which test a waiting job has not yet passed.
WhenUse a Wait for File job when:
- a later job needs a file that another system drops on the agent machine;
- the file is written slowly, and the next job must not read it half-written;
- a trigger file should be used once and then removed.
On a legacy LSAM machine, use that machine's own file-arrival job type instead — see Wait for a file to arrive.
How
- Choose Wait for File as the job type and set File Path to a path inside a directory the agent allows.
- Set Minimum File Size (bytes), Maximum File Age (seconds) or Stable For (seconds) if the file must meet them.
- Set Fail on Timeout off only if the workflow should go on without the file.
- Assign the job to a Universal Agent and save.
For the full steps, see Wait for a file before your workflow continues.
- The wait is always one hour at most. No setting changes it. Fail on Timeout only decides whether the hour ends in failure or success.
- The checks run in a fixed order: the path is a file, then minimum size, then maximum age, then stability. A size change starts the stability timer again.
- With Delete After Detection on, the file is removed once every check passes.
- A path outside the allowed directories fails at once. By default the allowed directories are the
temp directories and the agent's working directory. Setting
OPCON_ALLOWED_FILE_PATHSon the agent replaces that list rather than adding to it. - A Maximum File Age (seconds) that is too short means an old file never passes, and the job waits the full hour.
- Without Minimum File Size (bytes) or Stable For (seconds), the job can pass on a file that is still being written.
- Kill does not stop the wait on a Universal Agent.
Task walkthrough: Wait for a file before your workflow continues. This page is the full configuration and troubleshooting reference.
The Wait for File job pauses a workflow until a file appears at a given path and
meets optional size, age, and stability criteria. It can delete the file once detected.
It is a built-in job type (builtin:file-wait), so no plugin download is required.
| Property | Value |
|---|---|
| Job type | Wait for File (file-wait) |
| Runs on | Universal Agent only |
| Operating systems | Windows, Linux, macOS |
| Connections required | None |
| Category | Utility |
How it works
When the job starts, the agent polls the file path on a fixed interval until either all configured criteria are met (success) or one hour has passed.
On each check, criteria are evaluated in this order. The first unmet criterion ends the check and the agent waits one interval before rechecking:
- Exists and is a file — if the path is missing, or exists but is a directory, keep waiting.
- Minimum size — if Minimum File Size (bytes) is set and the file is smaller, keep waiting.
- Maximum age — if Maximum File Age (seconds) is set and the file was last modified longer ago than that, keep waiting.
- Stability — if Stable For (seconds) is set, the size must stay unchanged for that long. Any size change restarts the stability timer.
When every criterion is satisfied, the job records the file size and modified time, optionally deletes the file, and finishes successfully.
Configuration reference
| Parameter | Required | Default | Range | Notes |
|---|---|---|---|---|
| File Path | Yes | — | 1–4096 characters | Must resolve inside an allowed directory (see Path restrictions). |
| Check Interval (seconds) | No | 10 | 1–3600 | How often the agent rechecks the file. |
| Minimum File Size (bytes) | No | unset | 0 or more | Wait until the file is at least this many bytes. |
| Maximum File Age (seconds) | No | unset | 1 or more | File must have been modified within this many seconds (i.e. be recent). |
| Stable For (seconds) | No | unset | 1–300 | Wait until the size is unchanged for this long. Use for files still being written. |
| Delete After Detection | No | Off | — | A switch. Turn it on to delete the file after all criteria are met. |
| Fail on Timeout | No | On | — | A switch. If the timeout is reached: on fails the job, off finishes it successfully. |
The platform sends every Universal Agent job with a fixed 3,600-second timeout, and neither these parameters nor any setting on the job change it. Fail on Timeout only decides what happens when the hour is up.
Outcomes
| Result | Exit code | When |
|---|---|---|
| Success | 0 | All criteria met before the timeout. |
| Success on timeout | 0 | Timeout reached and Fail on Timeout is off. |
| Failed — timeout | 1 | Timeout reached and Fail on Timeout is on. |
| Failed — invalid parameters | 1 | A parameter fails validation (e.g. File Path empty, value out of range). |
| Failed — path not allowed | 1 | File Path resolves outside the allowed directories. Fails immediately, without waiting. |
| Failed — cancelled | 1 | The agent shuts down while the job is waiting. Kill does not reach a Universal Agent, so it does not end the wait — see How a Universal Agent takes and runs work. |
The job output is a running log of each check ("File not found, checking again in 10s", "File size 512 < minimum 1024", "File found and meets all criteria", etc.), which is the fastest way to see which criterion a stuck job is waiting on.
Path restrictions
File Path must resolve inside a directory the agent allows; anything else fails immediately rather than waiting. By default the allowed directories are:
/tmp/var/tmp- the operating system temp directory
- the agent's working directory
An administrator can override the list with the OPCON_ALLOWED_FILE_PATHS environment
variable on the agent (comma-separated paths). Setting it replaces the defaults — it
does not add to them.
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| Job fails instantly with a "path is outside allowed directories" error | File Path is not under an allowed directory | Move the file into an allowed directory, or have an admin add the location to OPCON_ALLOWED_FILE_PATHS on the agent and restart it. |
| Job waits the full hour, then times out — file is clearly present | Maximum File Age (seconds) set too low; an existing-but-old file never satisfies the age check | Raise or remove Maximum File Age (seconds). Use it only when you specifically need a freshly written file. |
| Job never succeeds on a file that keeps growing | Stable For (seconds) set, but the file is still being written, so the stability timer keeps resetting | Confirm the producing process has finished; raise Check Interval (seconds) or Stable For (seconds) to span the write, or remove the producer's lock/partial writes. |
| Job succeeds but downstream job gets an empty/partial file | No Minimum File Size (bytes) or Stable For (seconds), so the job matched the file mid-write | Add Minimum File Size (bytes), Stable For (seconds) or both so the file is complete before the job finishes. |
| File arrives but is never picked up; output says "Path exists but is not a file" | A directory exists at the File Path | Correct the path to point at the file, not its folder. |
| Job finished OK but the file is gone | Delete After Detection is on | Expected. Turn it off if a later job needs the file. |
| Expected a failure on a missing file, but the job finished OK | Fail on Timeout is off | Turn Fail on Timeout on if a missing file should fail the workflow. |
| Job assigned but never runs | Target agent is not a Universal Agent | Wait for File runs only on Universal Agents. Reassign to a Universal Agent. |
Contact support when
- The job fails with an error that is not one of the cases above (e.g. a permission or I/O error on a path that is allowed and present).
- The file demonstrably meets every configured criterion within the timeout but the job still times out.
Include the job output log, the parameter values, the agent OS, and the agent's
effective OPCON_ALLOWED_FILE_PATHS value.