Respond to a stuck or failed Wait for File job
A Wait for File job is waiting for a file to arrive and meet its conditions. If one is stuck waiting or has failed, you can usually tell exactly why from the job's own output, and whether the fix is yours, the Builder's, or the Administrator's.
A Wait for File job sits waiting or fails, and it's unclear whether the file is late, in the wrong place, or being rejected by a condition. The whole workflow is stuck with no obvious cause.
Start with the job output
The job writes a line every time it checks the file. The most recent line tells you what it's waiting on right now. Open the job output and read the last line before doing anything else.
What the output is telling you
| Last output line | What it means | What to do |
|---|---|---|
File not found, checking again in …s | The file hasn't arrived yet | Confirm the upstream source actually produced the file (partner delivery, export job, etc.). If it should be there, the path may be wrong: escalate to the Builder. |
Path exists but is not a file | A folder is sitting where the file should be | Escalate to the Builder: the file path points at a directory. |
File size … < minimum … | The file is present but smaller than required, often still being written | Wait for the source to finish writing. If it's already complete and just small, escalate to the Builder to adjust the minimum size. |
File age …s > maximum …s | The file exists but is older than allowed, so it will never qualify | The job is waiting for a fresh file. Confirm whether a new file is due. If the existing file should count, escalate to the Builder. |
File size changed … / File stable for …s, need …s | The file is still being written and hasn't settled | Wait for the source process to finish. If it never settles, escalate to the Builder. |
… is outside allowed directories | The agent isn't permitted to read that location (job fails immediately) | Escalate to the Administrator: the folder must be allowed on the agent. |
Timeout after …s | The file didn't arrive (and meet its conditions) in time | See When a job times out. |
When a job times out
A timeout means the file never became ready within the job's time limit. Two outcomes are possible, by design:
- The job failed: the Builder set it to fail when the file is missing. Treat it like any failed job: confirm whether the file was supposed to arrive, then rerun once it has, or escalate.
- The job succeeded anyway: the Builder set the file as optional, so the workflow continued on purpose. No action needed.
Before rerunning, confirm the file is actually present and complete. Otherwise the job will simply wait and time out again.
Who to escalate to
- Builder: anything about the job's configuration: the file path, the size/age/stability conditions, or whether a timeout should fail the workflow.
- Administrator: "outside allowed directories" errors, or any case where the agent can't reach a folder it should.
When you escalate, include the job output and the file path the job was watching.
Related topics