fix(router): surface prerender render errors instead of baking them (#587) - #590

Fixes #587.

Problem

When a Prerender route's render throws at build time, the router's error boundary catches it inside resolveAllSegments, turns it into a normal type: "error" segment, and matchForPrerender serializes that error page as a successful prerender artifact. The build logs OK, exits 0, and at runtime the frozen error page is served as a healthy HTTP 200. The failure is silent: CI/status/smoke checks see 200 + valid HTML, so a fully broken page looks healthy.

This bit a real deploy: with preset: "vercel" and a Prerender(...) route whose render reads ctx.env (no buildEnv configured → ctx.env throws at build), every store category page shipped a "Something Went Wrong" error boundary as a 200. The framework already detected the error (the router's onError fired during the build) — it just didn't let that affect the prerender result or the exit status.

Root cause

matchForPrerender → resolveAllSegments wraps each segment in resolveWithErrorBoundary (helpers.ts). A thrown render error is caught there (only Response re-throws), converted by catchSegmentError into a type: "error" segment via the nearest boundary / DefaultErrorFallback, and returned as a successful array. matchForPrerender's only post-resolution checks are detectPrerenderPassthrough + a loader filter — it never inspects for error segments — so it bakes the error page. The existing catch → FAIL → throw in expandPrerenderRoutes never fires because nothing throws.

Fix

The pre-render path resolves segments with a build-only throwOnError flag, threaded through the single ResolveSegmentOptions type (matchForPrerender → resolveAllSegments → resolveWithErrorBoundary). With it set, a thrown render error is re-thrown to the build loop instead of converted into an error segment. The live request path leaves the flag unset, so runtime error boundaries are unchanged.

This also fixes a latent bug: throw new Skip() inside a render fn (documented in errors.ts) was swallowed by the same boundary — it now propagates correctly (the getParams() Skip path always worked).

A new prerender.onError plugin option chooses what the build does with the surfaced error, applied in both the prerender and static loops via a shared resolvePrerenderError helper.

Before / after (consumer)

// urls.tsx — a Prerender route whose render needs request-time data
export const CategoryPage = Prerender(
  async () => [{ slug: "new-arrivals" }, /* … */],
  async (ctx) => {
    const commerce = await makeClient(ctx.env); // throws at build when buildEnv is off
    return <Category data={await commerce.list(ctx.params.slug)} />;
  },
);

• Before: pnpm build logs OK /shop/new-arrivals, exits 0; runtime serves the baked "Something Went Wrong" page as a 200.
• After (default): pnpm build logs FAIL /shop/new-arrivals — ctx.env is not available during pre-rendering … and exits non-zero. You fix it: provide buildEnv, wrap in Passthrough(), or throw new Skip().

Opting out / per-route control

// downgrade build-failure to a warn-and-skip
rango({ prerender: { onError: "warn" } });

// or skip a single URL that knowingly can't render at build:
export const CategoryPage = Prerender(getParams, async (ctx) => {
  if (!canRenderAtBuild()) throw new Skip("needs request-time env");
  return <Category … />;
});

Semantics

onError: "warn" is a build-unblock, not a runtime contract for the skipped entry: the route falls through to normal resolution and may render live (handler still bundled) or 404 (once handler eviction runs for other baked entries). Use Passthrough() for a defined live fallback, throw new Skip() for an intentional skip, or the default "fail".

Code changes

• src/router/segment-resolution/fresh.ts — ResolveSegmentOptions.throwOnError; pass it to resolveWithErrorBoundary.
• src/router/segment-resolution/helpers.ts — resolveWithErrorBoundary re-throws when throwOnError (after the Response re-throw).
• src/router/prerender-match.ts — pass { skipLoaders: true, throwOnError: true }.
• src/vite/discovery/prerender-collection.ts + src/vite/utils/prerender-utils.ts — shared resolvePrerenderError policy helper (Skip/warn/fail) used by both expandPrerenderRoutes and renderStaticHandlers.
• src/vite/plugin-types.ts / discovery/state.ts / rango.ts — the prerender.onError option threaded to discovery.
• src/vite/router-discovery.ts — dev /__rsc_prerender endpoint stays quiet on Skip.
• src/router/segment-wrappers.ts / router-context.ts / prerender-match.ts — all four resolveAllSegments option surfaces routed through the shared ResolveSegmentOptions (no type drift).

Test plan

• Unit (src/router/__tests__/prerender-render-error.test.tsx): throwing render is surfaced (rejects with the original error; serializer never reached); throw new Skip() propagates as a Skip; healthy render still serializes — through matchForPrerender.
• E2e build-level (e2e/prerender-onerror.test.ts + dedicated e2e/prerender-onerror/ app): default build fails (FAIL /prerender-boom + original error); onError: "warn" build succeeds + skips; same for Static() handlers. The fixture has its own projectRoot, so its dist/ never races other e2e builds.
• pnpm run typecheck (13 packages)
• pnpm run test:unit:all (router 3964+57, cloudflare-basic 42+10, vite-rsc-demo 15+1, mini 16+1)
• pnpm run lint (0/0) · pnpm run format · pnpm check:e2e-bucketing
• Docs: prerender-api-design.md (Render Errors section), feature-map.md, feature-file-map.md, prerender skill.

Notes / call-outs

• Dev /__rsc_prerender is a deliberate build-only test gap. The endpoint edit is a cosmetic log refinement on a path that serves only non-Node runtimes; the behavioral change (matchForPrerender re-throwing) is unit-covered. A faithful dev test needs a non-Node fixture with buildEnv off — cloudflare-basic uses buildEnv: "auto", where the render-error repro can't occur. Documented in the test header.
• No "dynamic"/"bake" onError values. "bake" is the bug; a clean "dynamic" can't be offered for a plain Prerender() route (its handler is evicted), so Passthrough() is the explicit live-fallback path.