Troubleshooting

The failures people actually hit, what the platform is telling you, and the fix. Every one of these leaves its reason in the run’s events; read those before anything else.

“verify … → no match”

The step’s verify: matches: or contains: did not find its text in what the agent concluded. The check reads the step’s final reply, and its first line is the run’s headline — so a reporter that opened with “Done.” and put the verdict on line three fails a ^BAD check with the right verdict sitting there. Tell the agent the first line is the verdict, and move a step that cannot manage it to a stronger tier.

“each: the previous group produced no items”

each: lines splits what the previous step concluded into lines and found none. Usually the step wrote its list to a file and replied with a sentence. Either have it reply with the list, or use each: rows of <file> — a file has no turns and is the better contract for a list that must arrive exactly.

“over budget — $x spent of the flow’s $y”

The run crossed its budget: between two groups; the remaining steps were skipped. Look at which step spent it: a fast-tier agent writing a file one line per call, re-sending its whole context each time, is the usual culprit. Put model: on that step, tell the agent to write each file once, and set the cap at two or three times a normal run so real work never trips it.

“was denied: … is outside this workspace”

The agent reached for a path outside its workspace — /tmp/something, an absolute path, a checkout a tool made — and was refused. The message names the path it probably meant. It costs a turn, nothing more; if one step collects many, name the exact path in its prompt (workspace/storage/x.md, site_repo action=read path=…).

“this push is not live yet — runs in flight”

The push was accepted and will apply when the runs finish. A run parked at an approval gate counts. Decide the gate, or wait; foldrun deploy --force applies over a running flow when you mean it.

“missing type: — OKF requires a non-empty type on every concept”

A file under knowledge/ has no type: in its frontmatter. Add one (type: Reference is fine for a table or a list); the push is refused until it is there.

The run is parked and nobody knows

Check the account’s notify: — a workspace that declared its own block replaced the account’s whole, and may have dropped awaiting-approval. The dashboard banner shows every parked run across workspaces regardless.

It ran on the wrong model

model: resolves nearest-wins: the step, then the flow, then the agent. A flow with model: fast in its frontmatter runs every step on the fast tier whatever each agent says. The run trace names which level won (model: haiku — flow). Put model: on the step to lift one.

The schedule fired more often than it should

When day-of-month and day-of-week are both restricted, cron ORs them. 0 5 1-7 * 5 fires every Friday and every day of the first week. Use a plain day of month for a monthly job.

Approval emails have no links

The install has no FOLDRUN_PUBLIC_URL, or it points at an address that no longer resolves. The worker logs why, once. Set it to the origin people actually reach the install on.

A step’s file never appeared in Storage

The agent wrote to outputs/ (the run’s scratch, archived with the run) or to a path relative to somewhere it was not. Deliverables go to workspace/storage/; the run page’s Out column shows what actually landed and where.