[finding] `rethrowAsBetterAuthError` maps engine errors code-by-code, so each new engine code needs its own incident before it stops leaking as a bodyless 500

[huangyiirene]

Filed by the domain:identity seat (#6022) out of PR #7879's review, on that dev's own reported observation (open question 1). Observation-class — nothing is broken today, which is why this is a finding and not a queue card. Unassigned; triage grades it.

The pattern

rethrowAsBetterAuthError in packages/plugins/plugin-auth/src/objectql-adapter.ts converts engine faults into better-auth APIErrors so they reach the client as a structured envelope. It matches by signature, arm by arm:

arm	added by	engine fault
validation errors	pre-existing	field/schema validation
policy refusals	pre-existing	authorization
DELETE_RESTRICTED	PR #7879 (#7724)	referential restrict

Anything not matching an arm falls through to throw err, and better-auth's router renders that as HTTP 500 with an empty body.

Two incidents so far, both the same shape, both found the expensive way:

• invitation-scope-gates: accept-invitation → bodyless HTTP 500, invitation stays pending forever (UNIQUE constraint on sys_member) #7725 — a raw driver UNIQUE violation on accept-invitation → bodyless 500, invitation silently reverted to pending.
• admin-lifecycle: remove-user is non-atomic and can never succeed — 409 leaks as a bodyless HTTP 500, credential rows deleted without rollback #7724 — an engine DELETE_RESTRICTED 409 on admin/remove-user → bodyless 500, credential rows already deleted.

Each was diagnosed by a dev reading better-auth source to work out why the body was empty. Neither was found by a gate.

Why it is worth recording rather than fixing now

#7879's dev deliberately kept its arm narrow (code === 'DELETE_RESTRICTED') and reported the generalisation instead of taking it — correct under that card's scope ruling, and correct on the evidence: two measured codes is thin ground for remapping every better-auth route under one predicate.

But the shape is worth naming: the engine already declares a numeric status on these errors. A rule like "any engine error carrying a 4xx status maps to the matching APIError" would consume what the producer already states, instead of re-enumerating it downstream — the contract-first direction. As it stands, the third engine code will need a third incident, and the incident is a silent one: an empty body is the hardest failure to attribute, and in both cases so far it was hiding a state change that had already happened.

⚠️ Before acting on this, measure the blast radius

Not a cleanup. Widening the predicate changes the response shape of every better-auth route at once, so it needs:

• an inventory of which engine codes can actually reach this seam, and what status each declares;
• a check that no route currently relies on a fault staying unmapped;
• the same predict-then-mutate ablation discipline fix(identity): make admin remove-user atomic, cascade sys_member, and map DELETE_RESTRICTED to a 409 #7879 used, since a mapping that silently swallows a fault reads exactly like a mapping that translates one.

Related

#7724 / PR #7879 (the DELETE_RESTRICTED arm and the source-level diagnosis) · #7725 / PR #7796 (the UNIQUE-violation instance; its symptom is resolved at the invitation layer, but the mapping class was left alone) · #7880 (the other finding from the same review)

[hotlong]

Triage: routed domain:identity (packages/plugins/plugin-auth/src/objectql-adapter.ts); hold as finding stands — the filer's own reasoning is the grade: two measured incident codes is thin ground for a predicate that changes the response shape of every better-auth route at once, and the generalization ("any engine error carrying a 4xx status maps to the matching APIError" — consuming what the producer already declares) needs the blast-radius inventory the card specifies before it is dispatchable.

Restart conditions: (a) a third bodyless-500 incident of this class — at that point the enumeration approach is measurably losing to the general rule and this promotes with the incident as evidence; (b) the identity lane doing the inventory (which engine codes reach this seam, what status each declares, does any route rely on a fault staying unmapped) — with that in hand this becomes a normal queue card.

---

Generated by Claude Code

[hotlong]

Triage (findings round): graded — held as finding.

Why held: nothing is broken today; two measured incidents are thin ground for a predicate that remaps every better-auth route at once, and the card's own blast-radius checklist (inventory of reachable engine codes, check that no route relies on a fault staying unmapped, predict-then-mutate ablation) is real work that should be bought when the evidence is thicker. The contract-first direction ("any engine error carrying a 4xx status maps to the matching APIError" — consume what the producer declares) is recorded and agreed as the shape when it is taken up.

Re-grade trigger, binding: a third incident of this shape — any engine code reaching a better-auth route as a bodyless 500 — promotes this card to pm:queue as a Bug immediately, with the generalisation (not another single-code arm) as the scope. Two arms was defensible narrowness; a third would be enumerating a producer contract downstream, which is the drift this repo's rules exist to stop.

---

Generated by Claude Code

[hotlong]

State-machine migration, maintainer-authorized (2026-08-13, live triage session: 「我授权你先迁标签」; semantics on #8449): graded hold with a binding promote trigger (third bodyless-500 incident ⇒ pm:queue as Bug, generalisation scope) — finding → pm:on-hold. Verdict, trigger, domain unchanged.

---

Generated by Claude Code