Every data primitive throws on a non-2xx before reading the response body, so the
server's own error message is unreachable. An app that wants to show "That email is already
a member" instead of "HTTP 422: Unprocessable Entity" cannot use useQuery, useMutation
or useFetch at all.
This is not a nitpick about error text. It is, as far as I can tell, the single reason a
real app on stx kept 23 hand-written fetch() calls through a deliberate campaign to remove
vanilla JS.
The code
packages/stx/src/signals.ts:1325 (useMutation):
var response = await __stxFetch('useMutation', resolvedUrl, fetchOpts);
if (!response.ok) throw new Error('HTTP ' + response.status + ': ' + response.statusText);
var result = await response.json(); // <- never reached on failureThe same shape, same order, in all four implementations:
signals.ts:1245 | useQuery |
signals.ts:971-973 | useFetch (runtime) |
composables/use-fetch.ts:211-212 | useFetch (module) |
The error signal then carries only that synthesized string —
error.set(e.message \|\| 'Query failed') (signals.ts:1256).
There is no escape hatch. options.transform runs only on the success path
(signals.ts:1247, :1327), so it cannot see a failure body either.
Why it forces a retreat to raw fetch
An app that needs the server's message has to write this, every time:
const res = await fetch(url, { method: 'POST', body })
const data = await res.json().catch(() => ({}))
if (!res.ok) { error.set(data.error || 'Something went wrong.'); return }Which is precisely what the app I measured does at 8 call sites — settings.stx:243-247
(rotate key), :446-450 (add channel), projects/new.stx:49-53, login.stx:51-54,
AutofixPanel.stx:202-203, :228-229, :254-255. Every one reads the body first solely
to reach data.error.
Adopting useMutation would silently downgrade every one of those messages. That is a
product regression, so the primitive is unusable for mutations that can fail meaningfully —
which is all of them.
What peers do
- ofetch / Nuxt —
FetchError.datacarries the parsed body, soerror.value.data.messageworks. - React Query —
mutationFnis your own function; you parse and throw whatever you like. - Axios —
error.response.data. - SWR — you supply the fetcher, same as React Query.
All four treat "the body of a failed response" as the primary error payload. stx discards it.
Suggested direction
Attach the body to the thrown error rather than changing the throw/no-throw contract:
if (!response.ok) {
const body = await response.json().catch(() => undefined)
const err = new Error('HTTP ' + response.status + ': ' + response.statusText)
err.status = response.status
err.data = body // <- the part that is missing
throw err
}error() would keep returning the same string it does today, so nothing breaks, and
error().data?.error becomes reachable. Worth applying to all four implementations at once,
since they are copies of each other.
Two adjacent notes:
- Stacks already ships a helper shaped for exactly this —
describeResponseError(status, body)at@stacksjs/browser/dist/composables/request-error.d.ts:1-12, whose doc comment describes this pattern. It is not inSTX_RUNTIME_GLOBALS, so a client script cannot reach it. - A
text/plainor empty body should degrade to today's behaviour rather than throw inside the error path.