reliant workflow lint reads the workflow file and flags those steps before the first firing. This guide lints a nightly workflow with eight kinds of problem, then fixes each one.
Lint is separate from validation. Validation asks whether a workflow can run. Lint asks whether it will still behave when nobody is watching it. Workflow lint describes every rule. This guide shows the ones an unattended workflow hits most.
Before you begin
- The
reliantCLI, v1.21 or later (reliant version). Lint needs no account and no network. - A workflow with
triggers:. Run an AI agent on a schedule shows how to write one.
1
Lint a workflow written without unattended runs in mind
This workflow updates dependencies every night and has an agent fix whatever breaks. Each finding names its rule and the node, and ends with a link to the rule’s section of the docs (trimmed here). An error makes the command exit
concurrency: {max_running: 1} lets only one run at a time, so a stuck run blocks every later night..reliant/workflows/nightly-deps.yaml
terminal
1. A warning is printed and the command still exits 0. reliant workflow validate runs the same rules, so the same four errors fail validation too.2
Bound every step that can hold the slot
With
max_running, anything that can wait without limit is an error (slot-unbounded-wait). Without concurrency:, the same file gets warnings instead: [loop-unbounded] attempts and [run-no-timeout] on update and attempts.test.- Commands: give each
runnode atimeout:, the longest the command may take. Without one, it runs for the 30-day default. - The loop: add
&& iter.iteration < 3towhile, so a fix that never works ends after three rounds. - The agent: give it a turn limit. In v1.21.3
builtin://agenttakes none, so the fixed version below usesbuiltin://structured-agentwithmax_turns: 60, the agent used for structured results in Write your first multi-agent workflow. Later releases acceptmax_turnsonbuiltin://agenttoo: set it there and keep the agent. Left at0(no limit), lint names the arg to set, as a warning.
timeout: 45m from fix. A workflow node dispatches no activity of its own, so its timeout: bounds nothing (timeout-ignored).3
Remove the step that approves its own gate
approve calls the approvals API with a saved token, so the workflow could approve requests, including the ones its own run raises. Lint cannot see what the token allows, so it treats any token that can decide approvals as able to (approval-decider). This workflow has no reason to approve anything, so delete the step.When approving is the job of a workflow, declare it with permissions: [approvals:decide] and allow the finding on that key, with the reason:.reliant/workflows/approve-bot.yaml
lint:allow with no reason is itself an error: [lint-allow-invalid] lint:allow approval-decider gives no reason.4
Make every failure reach someone
- Read the exit code. A non-zero exit does not fail a
runnode. Routeupdateonnodes.update.exit_code, so a failed update goes to a failure ending instead of to the agent. - Add
on_failure:. A run that fails, or ends at a node withoutcome: failure, then saves a message that tells someone. - Declare the tools.
requires: {tools: [npm]}makes a machine withoutnpmfail before the first step, not halfway through. - Add scenarios for the trigger and both endings, as in Test AI agent workflows with scenarios.
5
Verify the workflow is clean
The fixed workflow:With two scenarios in For CI,
.reliant/workflows/nightly-deps.yaml
.reliant/workflows/nightly-deps/scenarios/ (the nightly firing ending at green, and three red rounds ending at still_red):terminal
reliant workflow lint --json prints each finding’s rule, severity, node, message, fix and docs. To lint and validate in one gate, run reliant workflow validate --base origin/main, which also reports trigger changes that would break existing activations.What this does not do
- It does not stop a workflow from running. Lint never runs when a workflow is saved or started, so a rule added in a later release cannot stop an automation that already fires. Gate your repository on
validateorlintyourself. - It reads only the file. Lint never runs the workflow, and it cannot see what a saved connection or a hosted secret can do. A clean lint does not mean every path works: that is what scenarios test.
- It bounds steps, not spend.
max_turns, loop bounds and timeouts cap how long each step runs. They do not set a token budget for the run.
Troubleshooting
[slot-unbounded-wait] … the child's loop builtin://agent → agent_loop has no iteration bound
[slot-unbounded-wait] … the child's loop builtin://agent → agent_loop has no iteration bound
Reliant releases before
builtin://agent took max_turns report the agent this way, as an error whose fix text (editing the loop’s while) you cannot follow, because the loop is inside the built-in agent. On those, use builtin://structured-agent with max_turns. On a release whose finding reads “is bounded only by its max_turns input”, set args.max_turns on the node. Or, if you have judged that the agent’s run is bounded enough, allow the finding on the node with # lint:allow slot-unbounded-wait — <why>.[lint-allow-invalid] lint:allow … gives no reason
[lint-allow-invalid] lint:allow … gives no reason
Write the reason after the rule ID:
# lint:allow <rule> — <why it is fine here>. The rule ID must be one that reliant workflow lint --rules lists.validate lists lint warnings but its summary says Warnings: 0
validate lists lint warnings but its summary says Warnings: 0
In reliant v1.21.3 the
Warnings: count in the validate summary does not include lint warnings. Read the Lint warning: lines above the summary, or run reliant workflow lint, whose last line counts them.Next steps
Test AI agent workflows with scenarios
Cover every trigger and ending with mocked runs.
Run an AI agent on a schedule
Turn the trigger on and watch its firings.
Loop an agent until tests pass
A bounded fix-and-test loop, step by step.
Workflow lint rules
Every rule, its severity and how to fix it.