notFoundComponent cannot be rendered on prerendered routes

Which project does this relate to?

Start

Describe the bug

Currently, if you access a 404 page in a fully prerendered app, it will not render anything.
I have deployed a static website on Cloudflare Pages, and there seemed to be no way to render a 404 in production.

On cloudflare pages, a 404.html in root will be used to render a not-found page.

https://developers.cloudflare.com/pages/configuration/serving-pages/#not-found-behavior

I have tried the following configuration to manually output a 404.html.

      prerender: {
        enabled: true,
        autoSubfolderIndex: true,
        crawlLinks: true,
      },
      pages: [
        {
          path: "/404",
          prerender: { enabled: true, outputPath: "/404.html" },
        },
      ],

If you access a non-existent page with JS disabled, you will see the 404 page, but with JS tanstack will hydrate with an empty page.

If you prerender a non-existent route with

        {
          path: "/this-route-doesnt-exist",
          prerender: {enabled: true}
        }

the build will fail (as expected), because you would want prerendering to fail if there was an error.

Maybe we should be able to configure in a way that we allow 404 to be prerendered?

Reproduction:
URL: https://tanstack-start-404.pages.dev/a
Actual 404 route: https://tanstack-start-404.pages.dev/404 (prerendered automatically from 404.tsx)
GitHub: https://github.com/taroj1205/tanstack-start-5427-not-found-component

Your Example Website or App

https://github.com/taroj1205/tanstack-start-404

Steps to Reproduce the Bug or Issue

Go to https://tanstack-start-404.pages.dev/a
See empty page

Expected behavior

As a user, I expect a not found component or 404.html being rendered.

Screenshots or Videos

JS Disabled:

JS Enabled:

Platform

Router / Start Version: 1.132.0
OS: Windows 11 (WSL)
Browser: Helium
Browser Version: Version 0.4.12.1 (Official Build, Chromium 140.0.7339.207)
Bundler: vite
Bundler Version: 7.1.7

Additional context

Conversation on discord: https://discord.com/channels/719702312431386674/1238170697650405547/1425979592010760274

We've experienced what I think is a similar problem and have a proposed PR #5686 incase its any use

@taroj1205

We've merged #5686 - @taroj1205 , would you mind checking if this issue is resolved?

@birkskyum

@birkskyum I've tried updating the version to 1.139.0, but the issue seem to persist
commit: taroj1205/tanstack-start-5427-not-found-component@283a2da
404 link: https://724ae9cc.tanstack-start-404.pages.dev/a
Please tell me if I'm doing something wrong.

@birkskyum I've tried updating the version to 1.139.0, but the issue seem to persist commit: taroj1205/tanstack-start-5427-not-found-component@283a2da 404 link: https://724ae9cc.tanstack-start-404.pages.dev/a Please tell me if I'm doing something wrong.

Are you throwing via Tanstack router's notFound error?
i.e.
import { notFound } from '@tanstack/react-router';
Examples: https://tanstack.com/router/latest/docs/framework/react/api/router/notFoundFunction#examples

The fix we added will only catch and process an error that returns true when passed to the isNotFound function.

@roduyemi

@roduyemi ah that would be a different issue then. I am trying to render a not found page for the app for when accessing a nonexistent route.

@birkskyum I've tried updating the version to 1.139.0, but the issue seem to persist commit: taroj1205/tanstack-start-5427-not-found-component@283a2da 404 link: https://724ae9cc.tanstack-start-404.pages.dev/a Please tell me if I'm doing something wrong.

Are you throwing via Tanstack router's notFound error?
i.e.
import { notFound } from '@tanstack/react-router';
Examples: https://tanstack.com/router/latest/docs/framework/react/api/router/notFoundFunction#examples

The fix we added will only catch and process an error that returns true when passed to the isNotFound function.

Seeing that the issue still open and the repro still having the error - is there a recommended way for dealing with this on a Cloudflare Workers environment by now?

A workaround that worked for me for a fully static/prerendered site on Cloudflare Pages:

wrangler.jsonc:

{
  // ...
  "assets": {
    "directory": "./dist/client",
+   "not_found_handling": "404-page",
  },
}

start config in vite.config.ts, basically just render /404 to /404.html instead of /404/index.html, and exclude from sitemap

tanstackStart({
  prerender: {
    enabled: true,
    autoSubfolderIndex: true,
    autoStaticPathsDiscovery: true,
  },
  sitemap: {
    enabled: true,
    host: "https://yoursite.com,
  },
  pages: [
    {
      path: "/404",
      prerender: { enabled: true, outputPath: "/404.html" },
      sitemap: { exclude: true }, // <- exclude 404 from sitemap
    },
  ],
}),

Then create the routes that reuse your existing notFound component: /routes/404.tsx and /routes/$.tsx

import { createFileRoute } from "@tanstack/react-router";

import { DefaultNotFound } from "@/components/default-not-found";
// reuse your notFound component

export const Route = createFileRoute("/$")({ // do this for /404 too
  component: DefaultNotFound,
  ssr: false, // optional, you might want to consider this for /$
});

I guess the caveat here is that the 404 routes on /$ don't hydrate properly on load - there is a short flicker when trying to hydrate with a React error in browser console. ssr: false helps with this but the notFound component will only show after hydrating.

fix: docs spa 404 redirect for cloudflare + chunk size warning

Navigation Menu

Repository navigation

`notFoundComponent` cannot be rendered on prerendered routes #5427

Which project does this relate to?

Describe the bug

Your Example Website or App

Steps to Reproduce the Bug or Issue

Expected behavior

Screenshots or Videos

Platform

Additional context

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

notFoundComponent cannot be rendered on prerendered routes #5427

Description

Which project does this relate to?

Describe the bug

Your Example Website or App

Steps to Reproduce the Bug or Issue

Expected behavior

Screenshots or Videos

Platform

Additional context

Activity

matclayton commented on Nov 19, 2025

birkskyum commented on Nov 19, 2025

taroj1205 commented on Nov 27, 2025

roduyemi commented on Nov 27, 2025

taroj1205 commented on Nov 29, 2025

JonasDoesThings commented on Feb 7, 2026

dotnize commented on Mar 7, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

`notFoundComponent` cannot be rendered on prerendered routes #5427