How should a DataLoader batch function report a failure that affects only one of its keys?

## Two failure modes, and only one of them is right A batch function does bulk work on behalf of many independent field resolutions. That creates a question no single-item fetch has: when the work fails for *one* key, what happens to the other 213? The DataLoader pattern gives you two mechanisms, and they have very different blast radii. **Throwing (or returning a rejected deferred value) fails the whole batch.** The loader has one outcome to distribute and no way to tell which key it belonged to, so every deferred value it handed out for that batch is rejected with that error. In a restaurant ordering graph, one archived menu item that makes the catalogue call blow up takes down `menuItem` on every line of the page — a response that arrives half empty for a reason that concerned one row. **Placing an error value in a key's slot fails exactly that key.** The returned list still has one element per key; the element for the failed key is an error object rather than a value. The loader inspects each slot, and where it finds an error it rejects that key's deferred value only. Every other slot resolves normally. The execution engine then treats that one rejection as an ordinary field error: an entry in the response's `errors` array with the path of the field that asked for it, and `null` in the response at that path, subject to the usual non-null propagation rules of the field's type. ## When each is actually correct The choice is not stylistic; it follows the shape of the failure. * **Per-key errors** for failures that are genuinely about one key: a record that fails a downstream permission check, a row that violates an invariant the mapper cannot handle, an upstream bulk response that returned a per-item error entry for that identifier. Isolate it, let the rest of the page render. * **Whole-batch failure** for failures that are genuinely about the batch: the connection pool is exhausted, the bulk call timed out, the upstream returned 503. There is no honest per-key answer, and inventing 214 identical errors just makes the response noisier. Let it throw. Getting that backwards is the mistake interviewers listen for. Turning a pool exhaustion into 214 per-key errors hides an outage inside a partially successful response; turning one bad row into a batch-wide throw converts a one-row problem into a page-wide one. ## Why `null` is not a substitute Returning `null` in the slot for a failed key "works" in the sense that the list stays the right length and nothing throws. It is still wrong, because `null` already means something: **no such record**. Collapsing "absent" and "broken" into the same value destroys the distinction the client and your own dashboards need. A client can reasonably render "item unavailable" for an absent item; it should not render that for a catalogue outage. And the response carries no `errors` entry at all, so the failure is invisible to anyone reading the envelope — a silent hole is the worst of the three outcomes. ```pseudocode function loadMenuItems(keys): try: result = catalogue.findAllByIds(keys) # may raise: pool, timeout, 503 catch e: raise e # batch-wide: no per-key answer exists byId = index result.rows by id out = [] for k in keys: if result.perItemErrors.has(k): out.append(Error("menu item " + k + " unavailable")) # this key only else: out.append(byId.get(k) or null) # null == no such item return out ``` ## What the client sees The two mechanisms are indistinguishable in the schema and very distinguishable in the response. A per-key error produces a partial response: `data` still holds the order page, `errors` holds one entry whose `path` points at the exact line whose item failed, and that line's `menuItem` is `null`. A batch-wide throw produces an `errors` array with one entry per field that awaited the batch, all carrying the same message, and a much emptier `data`. If the field was declared non-null, the null bubbles up to the nearest nullable ancestor, which can turn one failed key into a missing order — a reason to think hard about nullability on fields fed by a loader. ## Operational notes worth saying out loud Give the per-key error a message that names the key's *class* rather than pasting an upstream exception into the response; the envelope is client-visible. Count per-key errors separately from batch failures in your metrics — they mean different things, and a rising per-key rate with a flat batch-failure rate is a data problem, not an infrastructure one. And a key that fails may be cached as a failure by the loader for the remainder of the request, so a retry within the same request will not re-attempt it; if a transient failure should be retryable, handle the retry inside the batch function where you still control the attempt.