remix-run/react-router · error · Error

Prerender (data): Received a ${response.status} status code

Error message

Prerender (data): Received a ${response.status} status code from `entry.server.tsx` while prerendering the `${url.pathname}` path.
${url.pathname}

What it means

Thrown by the postProcess hook of the RSC prerender pipeline when entry.server.tsx returns an unexpected HTTP status. Allowed statuses are: 200, 202, redirect codes (301,302,303,307,308), and 404 specifically for the /__spa-fallback.html SPA path. Any other status (e.g. 500, 404 on a real route, 401) aborts prerendering for that path, with the response attached as `cause`.

Source

Thrown at packages/react-router-dev/vite/rsc/plugin.ts:770

        }

        return Array.from(prerenderPaths).map(
          (prerenderPath) =>
            `http://localhost${basename}${prerenderPath.slice(1)}`,
        );
      },
      async postProcess(request, response, metadata) {
        let url = new URL(request.url);

        let isRedirect = redirectStatusCodes.has(response.status);

        if (
          !isRedirect &&
          response.status !== 200 &&
          response.status !== 202 &&
          !(url.pathname === "/__spa-fallback.html" && response.status === 404)
        ) {
          throw new Error(
            `Prerender (data): Received a ${response.status} status code from ` +
              `\`entry.server.tsx\` while prerendering the \`${url.pathname}\` ` +
              `path.\n${url.pathname}`,
            { cause: response },
          );
        }

        if (metadata?.manifest) {
          return [
            {
              path: url.pathname,
              contents: await response.text(),
            },
          ];
        }

        let isHtml = response.headers
          .get("content-type")

View on GitHub (pinned to 1fd704a7da)

Solutions

  1. Read err.cause (the Response) and its body — it usually contains the server-rendered error stack or loader message.
  2. If a loader needs build-time data, guard it with `import.meta.env` and provide prerender-safe fallbacks.
  3. Exclude the failing path from prerender config (prerender array / staticPaths) until the loader is prerender-safe.
  4. For auth-gated routes, return a redirect (302) instead of 401/403, or skip prerendering them.
  5. Reproduce locally with `pnpm build && pnpm prerender` (or the project's prerender script) and inspect the entry.server.tsx output.

Example fix

// app/routes/protected.tsx — before
export async function loader({ request }) {
  const user = await getUser(request); // throws 500 during prerender (no request session)
  return { user };
}
// after — skip work during prerender
export async function loader({ request }) {
  if (import.meta.env.REACT_ROUTER_PRERENDER) return json({ user: null });
  const user = await getUser(request);
  return { user };
}
Defensive patterns

Strategy: try-catch

Validate before calling

// before prerendering, dry-run each path against entry.server in dev
for (const path of prerenderPaths) {
  const res = await fetch(new URL(path, devOrigin));
  if (![200,202,301,302,303,307,308].includes(res.status) && !(path === '/__spa-fallback.html' && res.status === 404)) {
    console.warn(`Path ${path} will fail prerender with status ${res.status}`);
  }
}

Try / catch

try { await prerenderPath(path); }
catch (e) {
  if (e instanceof Error && e.message.startsWith('Prerender (data):')) {
    const body = await (e.cause as Response | undefined)?.text();
    console.error('Server error body:', body);
  }
  throw e;
}

Prevention

When it happens

Trigger: During prerendering (data mode + RSC), entry.server.tsx's render handler throws or returns an error Response (status 500, 403, etc.). A loader/action returning a non-redirect error Response. A 404 on a path that isn't the SPA fallback (route not matched but not in SPA mode).

Common situations: A loader throws during prerender because it expects runtime data unavailable at build time (env vars, DB). A route returns 401/403 for unauthenticated prerender requests. Misconfigured prerender paths that include routes with no matching loader. SSR errors (thrown in entry.server.tsx render) surfacing as 500.

Related errors

AI-assisted analysis of remix-run/react-router@1fd704a7da (2026-08-12). Data as JSON: /api/errors/0893f9a9e496c491. Report an issue: GitHub.