Wait for File job

Behavior-level reference for diagnosing Wait for File jobs.

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:

1. Exists and is a file — if the path is missing, or exists but is a directory, keep waiting.
2. Minimum size — if minSizeBytes is set and the file is smaller, keep waiting.
3. Maximum age — if maxAgeSeconds is set and the file was last modified longer ago than that, keep waiting.
4. Stability — if stableForSeconds 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	Type	Required	Default	Range	Notes
filePath	string	Yes	—	1–4096 chars	Must resolve inside an allowed directory (see Path restrictions).
checkIntervalSeconds	number	No	10	1–3600	How often the agent rechecks the file.
minSizeBytes	number	No	unset	≥ 0	Wait until the file is at least this many bytes.
maxAgeSeconds	number	No	unset	≥ 1	File must have been modified within this many seconds (i.e. be recent).
stableForSeconds	number	No	unset	1–300	Wait until the size is unchanged for this long. Use for files still being written.
deleteAfterDetection	boolean	No	false	—	Delete the file after all criteria are met.
failOnTimeout	boolean	No	true	—	If the timeout is reached: true fails the job, false finishes it successfully.

A Wait for File job waits at most one hour. 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. failOnTimeout 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 failOnTimeout is false.
Failed — timeout	1	Timeout reached and failOnTimeout is true.
Failed — invalid parameters	1	A parameter fails validation (e.g. filePath empty, value out of range).
Failed — path not allowed	1	filePath resolves outside the allowed directories. Fails immediately, without waiting.
Failed — cancelled	1	The job is cancelled while waiting.

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

filePath 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	filePath 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	maxAgeSeconds set too low; an existing-but-old file never satisfies the age check	Raise or remove maxAgeSeconds. Use it only when you specifically need a freshly written file.
Job never succeeds on a file that keeps growing	stableForSeconds set, but the file is still being written, so the stability timer keeps resetting	Confirm the producing process has finished; raise checkIntervalSeconds/stableForSeconds to span the write, or remove the producer's lock/partial writes.
Job succeeds but downstream job gets an empty/partial file	No minSizeBytes or stableForSeconds, so the job matched the file mid-write	Add minSizeBytes and/or stableForSeconds 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 filePath	Correct the path to point at the file, not its folder.
Job finished OK but the file is gone	deleteAfterDetection is true	Expected. Disable it if a later job needs the file.
Expected a failure on a missing file, but the job finished OK	failOnTimeout is false	Set failOnTimeout to true 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.