Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Error handling & error boundaries

Route each failure through a Decision on the step's outcome to an Error Boundary that logs, compensates, alerts or gives up, and ends at its own End instead of the happy path's.

A step with one way out

A company ships firmware to 40,000 smart thermostats overnight. The flow the team drew is a straight line: Update offered → Fetch image → Flash firmware → Updated. The rollout report the next morning counts every device that reached the end and says 100%. Support counts 212 thermostats stuck on a reboot loop. Nothing in the diagram was wrong about the happy path. It just had no other path, and the code built from it treated "the step finished" as "the step worked".

On the Grid that gap is structural. A Process has exactly one output there: Flash firmware cannot send its failures down a second edge, so whatever happens inside it, the arrow leads to Updated. The unhappy path has to be drawn as something of its own. A Decision asks about the step's outcome, and its no branch goes to an Error Boundary, the node that catches the failure and decides what happens next. Drawing it makes the failure path a first-class part of the design instead of an afterthought.

Two failure points, two different catches

The left column is still the flow the team meant. What changed is that each step that can fail is followed by a question about how it went, and each no leaves the column for a boundary of its own. An Error Boundary on the Grid has one input and one output, the same as a Process, so it also has to lead somewhere: here, to an End that names the outcome.

What the catch does, and where it lands

The boundary's label is a promise about what the handler does, and most handlers do some mix of four things. They log: write down which device, which versions, which check failed, so someone can find the pattern later. They compensate: undo the effect a step already had, as "Roll back, alert" does by switching the thermostat back to the firmware it ran before, which works only when the device kept the previous version in a second slot and its bootloader can tell the new one failed to boot and switch back. They alert: tell a person, usually only past a threshold, because one failure in 40,000 can be noise while 212 are a reason to pause the rollout. And they give up: stop trying and leave the device in a known state.

Then the path ends, and where it ends matters as much as the handling. "Kept old version" is its own End. Wire the boundary into Updated instead and the rollout report counts a rolled-back thermostat as a success, which is the morning's bug drawn again with an extra box in it. Leave the boundary with no outgoing edge and that path never reaches an End: the reader cannot tell whether the device was given up on or the diagram is incomplete. A handler that recovers can also lead back into the flow, for example to download the image again; that is a loop, and Loops & retries draws it with a Merge, a cap on the attempts and a pause between them. When several steps have already done work that has to be undone, each undo is its own step; Compensating Action covers how those are designed.

Two failures, two handlers

The two boundaries in the diagram are not the same box twice. A checksum mismatch means the downloaded image is not the one expected, and since the check runs before flashing, the firmware the device runs has not changed yet, so the handling is cheap: throw the file away, log it, try again in the next night's window. A failed boot after flashing means the thermostat cannot start on the new version. That one needs the rollback now, and enough of them should page someone and stop the rollout.

Draw a single catch-all "Handle failure" box and the diagram no longer shows that the two need different responses. Unless the handler sorts them out inside, where no reader sees it, it either rolls back devices that never installed anything, or quietly retries devices that cannot boot the new version. The Grid nudges you here too: an Error Boundary accepts one incoming edge, so two failures cannot both point at the same one. When two failures really do deserve identical handling, put a Merge in front of one boundary and say so in its label; when they do not, give each its own.

NoteWhen the task throws an error, BPMN can draw this catch as an error event attached to the border of the task itself, with no separate Decision; BPMN events: timer, message & boundary covers it.

The flow shows where a failure goes once something has decided it is one; in a running system that is each step's own check or a Timeout, while Retry and Circuit Breaker shape what happens next, and Cascading failures: how one dependency takes down its callers shows what happens without them.

Three ways a login can go wrong

Open the OAuth Authorization Code Flow challenge. Its brief names three failures and asks that each reach error handling: the user denies consent at the provider, the state that comes back on the callback does not match the stored one, and the exchange of the code for tokens fails. Before drawing, decide what each handler should do. A denial is the user's choice, not a fault: it ends the login, with nothing to alert on. A state mismatch can be a forged callback, which is what the state parameter is there to catch, or just a stale browser tab; either way the handler rejects the callback and stops that login attempt, and the mismatch is worth logging as a security event. A failed exchange can be a hiccup at the provider, worth a "try again" for the user and an alert if it keeps happening. Then count: the challenge allows twelve nodes, and three boundaries with a failure End of their own make thirteen. Here the cap overrides the rule above: the three failures meet at a Merge before one Error Boundary, its label names what each one gets (no alert for a denial, a security log for a mismatch, an alert when exchanges keep failing), and it ends at a failure End of its own, not at the success End.

Practice this