Lesson 0014 · Core Designer · Module 3

Fail-Fast at the Right Boundaries

The question is never "should we fail?" — it's where. Fail early, at the boundary, loudly, and the error arrives with its address attached.

Reading ≈ 9 minPractice ≈ 25 min

Mission tie-in: fail-fast completes the Core Designer phase — it's how the domain core protects itself from the messy world around it.

Knowledge: fail where the cause lives

A bad value that travels is a bomb with a delayed fuse: it's written here, read there, and explodes in a third place, hours later, in unrelated code. Fail-fast means the bomb detonates at the moment and place of the cause, where the fix is obvious.

Three boundaries deserve loud failures:

1. The input boundary — data enters the system. Validate and refuse before work starts:

def schedule_meeting(request: MeetingRequest) -> Meeting:
    if request.end <= request.start:
        raise InvalidMeetingRequest("end must be after start")
    ...

2. The invariant boundary — domain rules (lesson 0011) refuse invalid transitions, whoever is asking:

class Meeting:
    def cancel(self, reason: str) -> None:
        if self._status is Status.CANCELLED:
            raise AlreadyCancelled(self.meeting_id)   # not a silent no-op
        self._status = Status.CANCELLED

The tempting alternative — returning quietly when the meeting is already cancelled — hides a real bug: something in the system believes it is cancelling a live meeting. Silence turns that into a mystery three days later; the exception turns it into a stack trace now.

3. The integration boundary — the outside world fails; errors surface as errors, not as None:

def process_batch(orders: list[Order], gateway: PaymentGateway) -> BatchResult:
    results = []
    for order in orders:
        try:
            charge_id = gateway.charge(order.total, order.token)
        except PaymentError as e:
            results.append(FailedOrder(order.order_id, str(e)))   # loud, per item
            continue
        results.append(PaidOrder(order.order_id, charge_id))
    return BatchResult(results)

Notice the shape: each failure is caught at the boundary where it can be handled (per-order), recorded loudly, and reported — versus lesson 0005's AI version that swallowed everything and returned early. The difference between "fail-fast" and "fragile": the first fails loudly at the right boundary; the second fails silently at the wrong one.

How a senior designer works the case

A payments API, forty pods, a rolling deploy at 02:00. Startup validates the whole config file strictly and refuses anything it does not recognise — a rule the team adopted after a missing signing key was silently defaulted to empty. Tonight someone ships a typo in an optional feature flag. Every replacement pod fails to boot, the rollout drains the healthy ones, and a service that could have answered every request is down for nineteen minutes.

What they look at first. Not the typo. The question of what the failing check was protecting, and what it took down. Strictness here was not wrong in kind; it was applied at one granularity to two kinds of configuration with opposite risk profiles.

The question they ask. "Does failing here prevent harm, or cause it?" A missing signing key means every subsequent request is processed unverified — failing prevents harm, and must happen before the pod takes traffic. An unparseable flag for a UI experiment means one feature stays off — failing causes harm, and nothing else.

The alternative they reject. The reflex fix, wrapping the config load in try/except and defaulting everything, restores availability by deleting the distinction. It also silently reinstates the original incident: the missing signing key becomes "signature verification disabled", discovered by an auditor rather than by a crash. Trading a nineteen-minute outage for an unbounded security failure is not a trade a senior takes.

REQUIRED = ("database_url", "signing_key", "gateway_url")

def load_config(raw: dict) -> Config:
    missing = [key for key in REQUIRED if not raw.get(key)]
    if missing:                                   # cannot serve correctly: refuse before traffic
        raise ConfigError("cannot start without: " + ", ".join(missing))

    flags, rejected = parse_flags(raw.get("feature_flags", {}))
    for key, problem in rejected:                 # optional: degrade, but countably
        log.error("ignoring feature flag %s: %s", key, problem)
        metrics.config_degraded.labels(key=key).inc()

    return Config(raw, flags=flags, degraded=tuple(key for key, _ in rejected))

The consequence over time. The line between "cannot serve" and "nice to have" is now a list in the source, so adding a required key is a visible diff someone argues about, rather than an accident of which parser ran first. Tonight's typo becomes one ERROR line and a tick on a gauge. The subtler win is that the degraded state is observable: a pod running without an optional feature is now distinguishable from a pod running correctly, which is the property blanket try/except destroys and the reason it keeps producing incidents that take days to attribute.

When this is the wrong move

• Best-effort features. Recommendations, enrichment, avatars, telemetry. A failure here should shrink the response, not replace it. Return the page without the panel and count the omission.
• Streaming ingest. One malformed record must not stop the stream. Dead-letter it with enough context to replay, and alert on the dead-letter rate rather than on the record.
• Startup dependencies that are merely late. Crashing because the database is not up yet is reasonable under an orchestrator that restarts you; crashing because it was slow for four seconds at 03:00 is a self-inflicted outage. Bounded retry with a deadline, then fail.
• Anywhere the failure costs more than the wrong answer. Name that judgment explicitly, in the code, next to the fallback — the next reader needs to know it was chosen rather than forgotten.

Skill: which boundary fails how?

Practice on your own code

Find a silent failure in your code: a swallowed exception, a return None hiding an error, an early return abandoning work. Decide the correct boundary, make the failure loud, and (if useful) add the per-item handling pattern.

In the lab: the phase-1 checkpoint contains a returns pipeline whose gateway call is wrapped in a bare except Exception that returns an empty result, so a failed refund is indistinguishable from a return with nothing to refund. You decide which boundary owns the failure and make the difference visible in the value that comes back.

# before: silent
def load_config(path):
    try:
        return yaml.safe_load(open(path))
    except Exception:
        return {}

# after: loud at the input boundary
def load_config(path: Path) -> dict:
    return yaml.safe_load(path.read_text())   # errors propagate with their cause

Read and watch deeper

• A Philosophy of Software Design, Ousterhout — ch. 10 "Define Errors Out of Existence": fail-fast's philosophical home.
• Clean Code, Martin — ch. 7 "Error Handling": why swallowed errors are structural defects.
• Release It!, Nygard — the stability patterns: where loud, early failure protects the whole system.
• Shore, "Fail Fast" (IEEE Software, 2004) — the short primary source that named the practice, including its warning that fail-fast is about making bugs visible, not about crashing more.
• Watch: ArjanCodes YouTube — search "error handling" or "exceptions".
• Next phase: lesson 0015, System Designer.
• Reference: Design Principles — fail fast and its counterpart, define errors out of existence.

Bring a swallowed-error site to your agent-teacher and decide the correct boundary together.