Break
Leaves the enclosing loop early.
Purpose
Stops the current loop immediately and continues the flow from after the loop's Loop End. Everything remaining in the loop body is skipped, and no further iterations run.
When to use it
- You found what you were looking for and the rest of the loop is pointless.
- There is nothing left to process — an empty list, no more items on screen.
- A guard condition means the loop should stop early.
When not to use it
- To end the whole flow — use Return or Stop.
- To skip just this pass — use Continue.
- Outside a loop — Break only means something inside a loop region.
Requirements
Break must sit inside a loop region. It belongs to the innermost enclosing loop, resolved at compile time.
How it runs
Break carries no user-wired outgoing edge. The compiler rewires it to the node after the enclosing loop's Loop End.
You do not draw an edge out of Break. The routing is generated.
Settings
| Setting | Type | Range | Notes |
|---|---|---|---|
| Label | string | ≤ 120 chars | Optional display label only; no runtime effect |
Break has no functional settings — its behaviour is entirely positional.
Ports
| Port | Notes |
|---|---|
| Success | Present on the node, but not user-wired — the compiler owns it |
| Fatal | Configuration fault. Never followed |
Break has no required ports. Wire an edge into it; do not wire one out.
Basic example
Stop a scan loop when nothing is found:
- Find Image → Failure → Break
Realistic example — bounded search
The loop has two exits — the iteration cap and Break — and the flow decides what happened afterwards from a counter.
Advanced example — retry region with early exit
Break turns a counted loop into a bounded retry:
Without Break, a successful first attempt would still burn the remaining two iterations.
Best practices
- Set a flag before breaking when the code after the loop needs to know why it ended.
- Use the Label field to say why —
"none left","target reached". - Prefer Break over letting a loop spin to its cap when the work is done.
- Keep Break in the loop you mean. In nested loops it applies to the innermost one.
- Do not wire an edge out of Break.
Performance notes
- Break itself is free.
- Its performance value is real: exiting a 5-iteration loop after the first pass saves four iterations of body work, which for a detection-heavy body is seconds.
Memory notes
- No allocation. Ending a loop early reduces the number of node results accumulated in the run context.
Common mistakes
| Mistake | What happens | Fix |
|---|---|---|
| Using Break to end the flow | Only leaves the loop | Use Return |
| Using Break to skip one pass | Ends the loop entirely | Use Continue |
| Wiring an edge out of Break | Not how it works | Wire only into it |
| Break in the wrong nested loop | Leaves the inner loop only | Check the region |
| No flag set before Break | Downstream cannot tell why the loop ended | Set a flag first |
Troubleshooting
Break does not leave the loop I expect. It applies to the innermost enclosing loop. Move it, or restructure the nesting.
The flow ends instead of continuing after the loop. Check what is wired after the Loop End — Break routes there, and if nothing is wired the run finalizes.
Break seems to be ignored. It is probably not on the executed path. Confirm the branch reaching it actually runs.
FAQ
Does Break have settings? Only an optional label.
Can I use Break outside a loop? No — it is meaningful only inside a loop region.
Does Break end the flow? No. Use Return or Stop for that.
How do I know the loop broke early?
Set a variable before the Break, or use Loop End's iterationCount aggregation.
Related nodes
- Loop — the region Break exits
- Continue — skip one pass instead
- Return — end the whole flow
- Variable — record why the loop ended