CS-11024: Defer prerender error status to afterRender

[habdelra]

Why this matters

A user-visible "indexing error" surface that hides the real underlying card error has been recurring across multiple realms in production. Every occurrence is a confused user and a noisy support thread; the actual card error (most often a wrong-subpath import or similar module-eval throw) never reaches them.

Repros deterministically on staging for buck/buck/SprintTask/7d92636a-…json across 4+ separate from-scratch attempts on different days, plus across multiple realms with the same pattern (bn3/bn, lukemelia/testing-2, etc.). All of them surface as the literal worker log render.html returned an invalid error payload: with empty value after the colon.

Mechanism

The prerender server's capture wait condition (packages/realm-server/prerender/utils.ts:765-779) treats two signals as equivalent — wait is satisfied when data-prerender-status ∈ {ready, error, unusable} OR the <pre data-prerender-error> has non-empty text:

let status = element.dataset.prerenderStatus ?? '';
const errorHasText = errorText.length > 0;
const hasError = errorElement !== null && errorHasText;
if (!statuses.includes(status) && !hasError) { continue; }   // keep waiting

The host is supposed to use data-prerender-status on the outer [data-prerender] container as the canonical "DOM is settled, snapshot now" signal. But in #processRenderError (packages/host/app/routes/render.ts), the old #applyErrorMetadata wrote prerenderStatus='error' synchronously, before #transitionToErrorRoute triggered the Ember transition that renders the render.error template. Until the template renders, the inner <pre data-prerender-error> is either absent or has stale/empty content.

Race window:

1. data-prerender-status='error' written ← prerender wait condition is satisfied here
2. Server poll fires, takes capture against the still-empty <pre data-prerender-error>
3. Ember transitions to render.error
4. Template renders {{this.reason}} into the <pre>

When the server polls between (1) and (4), the captured value is empty. JSON.parse('') fails, and renderCaptureToError synthesizes "render.html returned an invalid error payload: ". The actual card error never reaches the user.

The intent — and the contract this PR preserves — is that data-prerender-status='error' means the DOM is fully settled in an error state, not the route has decided to enter an error state. Today's code raised the signal at decision time rather than at settlement time.

Fix

Defer data-prerender-status='error' to fire after the render.error template has rendered, via Ember's afterRender queue. The id/nonce datasets stay where they are — those are immutable for this render and the server doesn't gate on them. Only the status flip moves.

• Split #applyErrorMetadata in packages/host/app/routes/render.ts into:
  • #applyErrorMetadataAttrs(context) — sets data-prerender-id and data-prerender-nonce on [data-prerender] and [data-prerender-error] synchronously. The server uses these for id/nonce parity checks; they're immutable for this render.
  • #applyErrorStatus(context) — sets data-prerender-status='error' on the outer container.
• #processRenderError now calls #applyErrorMetadataAttrs synchronously, then #transitionToErrorRoute(transition), then schedule('afterRender', this, this.#applyErrorStatus, context). Glimmer flushes the transitioned-to template's DOM updates before afterRender fires, so by the time we lift the readiness signal the <pre>'s textContent is populated.

Acceptance criteria (from CS-11024)

• ✅ After the fix, data-prerender-status='error' is set only after [data-prerender-error]'s textContent.trim().length > 0.
• ✅ data-prerender-id / data-prerender-nonce are still set synchronously, so id/nonce-based wait-condition checks continue to work.
• ✅ Window-error path (Path A) is untouched — it already orders the setError (textContent write) before the status flip via setStatusToUnusable in the wrapping handler.
• ✅ The buck/buck/SprintTask/7d92636a-…json indexing run will no longer log render.html returned an invalid error payload:. Worker error will become the actual underlying error (e.g. the proxy ReferenceError for the wrong-subpath import).

Out of scope

• Path A (window-error): already correct; orders textContent before status.
• Improving the strict-namespace proxy's error message to suggest the correct subpath. Tracked in CS-11023; pairs with this ticket so the actionable error reaches the user and the message itself is more useful.
• Worker-process crash investigation: separate concern, downstream of this fix — once the capture surfaces the real error reliably we can correlate which error classes correlate with worker exits.
• Adding a non-DOM side-channel for the error payload: the DOM is the single source of truth; the bug is in when we signal readiness, not in the surface.

Test

Adds a realm-server prerendering regression test at packages/realm-server/tests/prerendering-test.ts that drives a card whose module throws synchronously during evaluation (eval-throw.gts — throw new Error('module-eval-throw') at top level). Asserts:

• captured error message contains the actual underlying throw (module-eval-throw),
• captured error is not the synthesized "returned an invalid error payload" fallback,
• the failure is not classified as a timeout.

The test exercises the route-error path: module evaluation rejects → model() rejects → route's error action fires with the active transition → #processRenderError lifts status='error' → server captures and parses.

Test plan

• pnpm lint (host + realm-server)
• Realm-server prerendering test runs locally
• CI realm-server tests shard passes
• No regression on existing route-error tests (card prerender surfaces errors thrown before the render model hook, card prerender hoists module transpile errors, card prerender surfaces actionable error for bad icon import, etc.)

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 867430698c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

Preview deployments

• Host staging preview

• Host production preview

Host Test Results

    1 files  ±0      1 suites  ±0   1h 56m 55s ⏱️ - 2m 39s
2 563 tests +1  2 548 ✅ +1  15 💤 ±0  0 ❌ ±0 
2 582 runs  +1  2 567 ✅ +1  15 💤 ±0  0 ❌ ±0 

Results for commit 27375b8. ± Comparison against earlier commit 74b6e4a.

Realm Server Test Results

    1 files  ± 0      1 suites  ±0   18m 4s ⏱️ +55s
1 235 tests +22  1 235 ✅ +23  0 💤 ±0  0 ❌  - 1 
1 307 runs  +22  1 307 ✅ +23  0 💤 ±0  0 ❌  - 1 

Results for commit 27375b8. ± Comparison against earlier commit 74b6e4a.

[Copilot]

Pull request overview

This PR fixes a prerendering race in the Host app’s render route error handling by deferring the data-prerender-status="error" readiness signal until Ember’s afterRender, ensuring the render.error template has populated the <pre data-prerender-error> payload before the prerender server snapshots it.

Changes:

• Split error metadata writes so data-prerender-id / data-prerender-nonce are applied synchronously, while data-prerender-status="error" is scheduled on afterRender.
• Add a realm-server prerender regression test that exercises a module top-level evaluation throw and asserts the captured error surfaces the underlying throw instead of the synthesized “invalid error payload” fallback.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
packages/host/app/routes/render.ts	Defers raising the prerender “error settled” signal to afterRender to avoid capturing an empty error payload.
packages/realm-server/tests/prerendering-test.ts	Adds a regression test covering module-evaluation throws to validate the corrected prerender capture ordering.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.