A GraphQL request hangs with DataLoader keys queued and never dispatched — what causes it?

## Dispatch rests on an observation, and observations can be wrong A loader's queued keys leave when execution can make no further progress. In an engine that resolves fields on tasks or threads, that judgement is made by counting: fields started, fields completed, fields parked on a loader's pending result. When everything reachable is parked on a loader, the engine dispatches. The failure mode falls straight out of the mechanism. If a field is stuck on something the engine does **not** count as parked-on-a-loader, the engine believes work is still progressing, so it never dispatches — and the thing that field is stuck on may be exactly what a dispatch would have unblocked. Both sides wait, forever, and the request produces no response, no error and no log line until a timeout somewhere upstream gives up. ## Shape one: coordinating two resolvers by hand The one that actually happens, and it usually starts as an ordering assumption. On a parcel-locker graph, a team noticed that `Locker.parcels` needed the compartment rows that `Locker.compartments` had already fetched. `compartments` is written first in every document the client sends, so — the reasoning went — it resolves first, and `parcels` can just wait for what it produced: ```pseudocode resolve Locker.compartments(locker, ctx): rows = await ctx.compartmentLoader.load(locker.id) // engine sees: parked on a loader ctx.compartmentsReady.complete(rows) // hand-off return rows resolve Locker.parcels(locker, ctx): rows = await ctx.compartmentsReady // engine sees: a field still running return ctx.parcelLoader.loadMany(rows.map(r -> r.id)) ``` The assumption is wrong twice over. Field resolution order within a query selection set is not specified, and engines commonly resolve those fields concurrently — only a mutation's root fields are required to run serially. So both fields start. `compartments` parks on its loader, which the engine understands. `parcels` parks on a plain future, which the engine does not: to the engine that field is simply still executing, so execution has not stalled, so no dispatch happens, so the compartment keys sit in the queue, so `compartments` never completes, so `compartmentsReady` never completes. Deadlock. It shipped because the test document selected only `compartments`. The hang appeared the first time a client asked for both fields on the same locker. The fix is not a lock or a timeout. It is to let the loader be the coordination point: have `parcels` load the compartment rows itself. The loader's per-key memoization means the second ask costs nothing and shares the first fetch, and now both fields are parked on a loader, which is a state the engine can act on. ## Shape two: blocking a thread on a pending result Calling something like `.get()` or `.join()` on a loader's pending result inside a resolver looks harmless in a synchronous codebase and is the other reliable way to hang. The thread you have blocked is a worker the engine may need in order to run the remaining fields or the dispatch pass itself; you are holding it hostage against work that only that pass can start. With a small pool this can also strand a request that would otherwise have been fine, which is why it surfaces under load and not in a test. ## Shape three: keys queued after the last pass The subtler variant. If a batch function or a completion callback issues a `load` of its own, those keys arrive **after** the dispatch pass that triggered it. Whether they ever go out depends on whether the implementation re-arms — re-checks for queued keys once a batch completes, or lets the event loop schedule another dispatch naturally. Some do, some require you to opt into a strategy that does, and a chained load is exactly where you discover which. This is implementation behaviour, not specified behaviour, so verify it rather than assume it. ## Diagnosing a live one * Read the loader's counters for the stuck request: **keys loaded greater than zero with batch invocations at zero** is the whole diagnosis in one line. * Dump threads or inspect parked tasks and look at what the frames are waiting on. A resolver frame waiting on a lock, a queue, a countdown or a bare future — anything that is not the loader — is your culprit. * Bisect the document. Remove fields until the hang stops; the field you removed last and the field it was waiting for are the pair. * Reproduce with two selected fields on one object. Width does not matter here; the coupling does. ## Fixing, and the fallback that is not a fix Remove cross-field coordination from resolvers: every field should ask the loaders for what it needs and let dedup do the sharing. Never block a resolver on a pending loader result. Where a value truly must be computed once per request, compute it during request setup, before execution starts, not by having one field wait on another. A scheduled dispatch — send after a short delay whether or not execution has stalled — will unstick a deadlock, and it is worth knowing as an escape hatch, but be honest about the bill: that delay is paid on every dependency level of every request. A request timeout is not a fix either; it converts a hang into a 30-second error. Both are worth having in place while you remove the coupling that caused it.