Skip to content

fix(studio): name the cause when a render request fails - #3424

Merged
miguel-heygen merged 1 commit into
mainfrom
fix/studio-surface-render-request-error
Aug 22, 2026
Merged

fix(studio): name the cause when a render request fails#3424
miguel-heygen merged 1 commit into
mainfrom
fix/studio-surface-render-request-error

Conversation

@miguel-heygen

Copy link
Copy Markdown
Collaborator

What

Studio's render request now reports why it failed instead of collapsing every cause into
one sentence.

Why

useRenderQueue.ts wrapped the render POST in try { ... } catch { ... } — no binding, so
the exception was discarded:

} catch {
  error: "Could not reach render server. Use `hyperframes render` from the CLI instead.",

A dead server, a DNS failure, an aborted request and a server that died mid-render all
produce that identical string.

It is not only a UI message. It is the value that travels into the feedback report, so
three separate field reports arrived carrying it verbatim — one of them describing a
render that fails every single time. A guaranteed reproduction we cannot read is worse
than an intermittent one we can.

How

Bind the error, append it after the guidance:

} catch (err) {
  const cause = err instanceof Error ? err.message : String(err);
  ...
  error: `Could not reach render server: ${cause}. Use \`hyperframes render\` from the CLI instead.`,

The CLI suggestion stays — it is still the right next step for the user — it just no longer
stands alone.

Test plan

New useRenderQueueTransportError.test.tsx stubs fetch to reject with
TypeError("Failed to fetch") and asserts both halves of the contract: the cause appears,
and the guidance survives.

Verified it fails on the unfixed code rather than assuming:

× names the cause instead of collapsing every failure into one sentence
  → expected 'Could not reach render server. Use `h…' to contain 'Failed to fetch'

With the fix: 1 passed. Full packages/studio suite green at 4379 passed / 18 todo.

Not covered

  • This does not fix any underlying cause of the reported failures; it makes the next report
    diagnosable. The "happens every time" case remains open until a report arrives carrying
    the real error.
  • Only the transport catch is changed. The !res.ok branch below it already surfaces
    server-side detail and is untouched.

The render POST's catch took no binding, so the exception was discarded and
every transport failure produced one sentence: "Could not reach render server.
Use `hyperframes render` from the CLI instead."

A dead server, a DNS failure, an aborted request and a server that died
mid-render are all indistinguishable under that string — and it is not only a
UI message, it is what travels into the feedback report. Three separate field
reports carried it verbatim, one of them describing a render that fails every
single time. A guaranteed reproduction that tells us nothing is worse than an
intermittent one that does.

Bind the error and append it. The CLI guidance stays, since it is still the
right next step for the user; it just no longer stands alone.

Regression test asserts both halves: the cause appears, and the guidance
survives. It fails on the unfixed code with `expected 'Could not reach render
server. Use `h…' to contain 'Failed to fetch'`.
@miguel-heygen
miguel-heygen merged commit 7a024cf into main Aug 22, 2026
45 checks passed
@miguel-heygen
miguel-heygen deleted the fix/studio-surface-render-request-error branch August 22, 2026 15:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant