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 `${metadata.path}` path.\n${pathname}

What it means

Thrown in `postProcess` when `metadata.type === "data"`. For `.data` requests (turbo-stream loader output) React Router requires HTTP 200 or 202; any other status from `entry.server.tsx` is treated as a build-time failure because the prerendered `.data` file would be invalid. The thrown error captures the offending `Response` as `cause` for downstream handlers.

Source

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

        // When `ssr:false` is set, we always want a SPA HTML they can use
        // to serve non-prerendered routes.  This file will only SSR the root
        // route and can hydrate for any path.
        if (!ctx.reactRouterConfig.ssr) {
          requests.push(createSpaModeRequest(ctx.reactRouterConfig));
        }

        return requests;
      },
      async postProcess(request, response, metadata) {
        invariant(metadata);

        // Handle loader data responses
        if (metadata.type === "data") {
          let pathname = new URL(request.url).pathname;

          if (response.status !== 200 && response.status !== 202) {
            throw new Error(
              `Prerender (data): Received a ${response.status} status code from ` +
                `\`entry.server.tsx\` while prerendering the \`${metadata.path}\` ` +
                `path.\n${pathname}`,
              { cause: response },
            );
          }

          let data = await response.text();

          return {
            files: [
              {
                path: pathname,
                contents: data,
              },
            ],
            // After saving the .data file, request the HTML page.
            // The data is passed along to be embedded in the response header.

View on GitHub (pinned to 1fd704a7da)

Solutions

Reproduce the path locally with `react-router build && react-router preview` and open the `.data` URL to see the actual status/body.
Make the loader deterministic at build time (fallback to defaults instead of throwing for missing request data).
Remove the failing path from the `prerender` array or `prerender` function's returned list.
Return explicit redirects via the prerender-aware `redirect()` so the post-processor can render a meta-refresh fallback instead of erroring.

Example fix

// before: loader throws for prerendered path
export const loader = ({ request }) => {
  throw new Response("Not found", { status: 404 });
};
// after: provide build-time defaults
export const loader = ({ request }) => {
  return json({ items: FALLBACK_ITEMS });
};

Defensive patterns

Strategy: validation

Validate before calling

// Skip prerender entries whose loaders cannot succeed
const isSafeToPrerender = (path: string, dynamicPaths: Set<string>) =>
  !dynamicPaths.has(path);
export const prerender = async () =>
  allPaths.filter(p => isSafeToPrerender(p, unsafe));

Prevention

Make loaders deterministic for prerendered paths (no thrown errors).
Filter `prerender` lists against actually-routable, data-available paths.
Use `redirect()` for moves so the post-processor can render meta-refresh fallbacks.

When it happens

Trigger: A loader throws or returns a 4xx/5xx during prerendering; a `loader` redirects (3xx) for a path declared in `prerender`; the route is a `prerender` entry but its loader depends on request data unavailable at build time; `entry.server.tsx` returns an error response for that path.

Common situations: Listing a dynamic route in `prerender` whose loader reads `request.url` query params and 404s when none are present; loaders that throw on missing env vars during CI builds; a parent loader failing cascades to the child `.data` file.

Related errors

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