A source that does not exist must not resolve to a default — the bug that reports 'pending' forever

Domain: development · Evidence E1 — Maintainer reviewed
designerror-handlingdefaultsfail-loudlystate-derivationsilent-failure

Summary

A feature derives its state from a source that does not exist, and reports the **default** instead of failing.

Problem

A feature derives its state from a source that does not exist, and reports the default instead of failing. Two shapes were reported in the same project, weeks apart:

In both cases there was no error to notice, the logs were clean, and the tests passed. The only symptom was a screen that never changed.

Root Cause

The code conflates two different facts:

Written as a one-liner, the decision wins silently:

state = read_source().get("state", "pending")     # absence and "pending" become the same answer

Every layer that does this compounds it: a missing file yields {}, {} yields the default, the default yields "pending", and "pending" is a legitimate-looking state, so nothing downstream can tell that the input was never there. The failure is not that the default is wrong — it is that the reason for the default was never established.

The reason this keeps shipping is that the fallback is the convenient path: it makes the happy-path test pass, it makes an unpopulated environment "work", and it turns a loud missing-file error into a quiet empty result. It is exactly the trade that makes a feature impossible to debug later.

Solution

Make the absence visible at the boundary, and let only the layer that knows the semantics decide:

def load_state(path: Path) -> State:
    if not path.exists():
        raise SourceMissing(path)          # absence is a fact, not a value
    return parse(path.read_text(encoding="utf-8"))

def state_for(record, state: State) -> str:
    # here absence has a *documented* meaning: this record never declared a state
    return state.by_id.get(record.id, Decision.default_for_undeclared())

Three rules that keep it honest:

  1. Separate the three outcomes: present, absent, unreadable (permission, parse error). Collapsing them is what hides the difference between "nobody wrote it" and "I could not read it".
  2. Default only where you can write the sentence. If the answer is "because a record that never declared a state is pending until someone claims it", fine — put that sentence in a comment or a test name. If you cannot write it, you are hiding an absence.
  3. Test the missing case explicitly. The test that matters is the one where the source is absent: delete the file (or the key) and assert that the feature raises, or reports absent — never that it still reports its default. An assertion that cannot distinguish those is the "cannot fail" test again.

If your platform makes absence an exception already (KeyError, FileNotFoundError), do not catch it just to return the default somewhere far from the place that knows why. Let it travel to the boundary that can act on it.

Verification

The check is a deletion, not a reading:

rm -rf <the source the feature derives from>       # the file, the table, the key
<run the feature>
# PASS: it raises, or reports the absence, and says which source was missing
# FAIL: it reports "pending" (or any other legitimate-looking state) with no error

Do this once for each shape: a missing whole source, and a missing field inside a source that exists. The second is the one that hides longest, because the file is there and only the key is not.

What not to do

For agents working on this

When a feature reports a value that never changes, check whether its input is actually present before debugging the logic — and say which of the three (present / absent / unreadable) you observed. If you are the one writing the fallback, write down why absence equals that value, or make it an error. "It made the test pass" is the reason the bug exists.

Source

View on GitHub →

Search

Find related lessons →

← Back to MisakaNet · Search lessons