Workflow linter: catch risky automation steps before they run

workflow-lint is an open-source preflight linter that catches missing error handling, unsafe retries, unapproved money actions and hardcoded secrets in AI-agent and automation workflows before they run.

Who it is for

People who build or review n8n flows and AI agents that send email, charge cards, update a CRM or delete records. It is most useful right before you activate a workflow, and in CI so a risky change is caught in review.

How it works

workflow-lint converts the workflow into a list of steps and works out what each one does to the outside world: nothing, a write, an external send, a money movement, or a delete. Then it applies nine rules drawn from real automation failures:

• WL001 missing error handling, including steps that silently continue on error
• WL002 retried writes, sends or payments with no idempotency key
• WL003 external calls or open-ended waits with no timeout
• WL004 money, delete or external-send steps with no human approval gate
• WL005 workflows that never check the end state
• WL006 hardcoded API keys, tokens and private keys (redacted in the output)
• WL007 loops, pagination or execution cycles with no limit
• WL008 webhook triggers that do not verify a signature
• WL009 personal data sent to an LLM step with no handling note

Example

The "New order follow-up" sample n8n workflow produces 12 findings (7 errors, 5 warnings). Two of them:

error    WL002 unsafe-retry  line 55
         Step "Email Customer" retries up to 3 times but has no idempotency key;
         a retry after a timeout can repeat the send.
error    WL004 unapproved-high-risk-action  line 65
         Step "Charge Deposit" moves money without a human approval gate.

The fixed version reports zero problems. On the command line: npx @teamshift/workflow-lint workflow.json, or --format sarif for code scanning.

Limitations

• It reads n8n exports and its own generic spec. Describe workflows from other tools in the spec to lint them.
• Some n8n checks are heuristics, such as recognizing a "Verify…" node as a completion check. A clean report is a floor, not proof that a workflow is safe.
• It checks structure, not behavior. It cannot tell whether an approval step is ever answered or whether a timeout is the right length.

FAQ