Prerendering appears broken in latest

[arackaf]

Which project does this relate to?

Start

Describe the bug

Prerendering appears broken in latest version of start. Repro can be found in this repo (note the branch name - feature/prerender-repro):

https://github.com/arackaf/tanstack-blog-blog-post/tree/feature/prerender-repro

With the CloudFlare plugin, the error looks like this

[prerender] Prerendering pages...
[prerender] Concurrency: 16
[prerender] Crawling: /
[prerender] Prerendered 0 pages:
file:///Users/arackis/Documents/git/tanstack-blog-blog-post/node_modules/@tanstack/start-plugin-core/dist/esm/prerender.js:126
            throw new Error(`Failed to fetch ${page.path}: ${res.statusText}`, {
                  ^

Error: Failed to fetch /: Not Found
    at file:///Users/arackis/Documents/git/tanstack-blog-blog-post/node_modules/@tanstack/start-plugin-core/dist/esm/prerender.js:126:19
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
    at async file:///Users/arackis/Documents/git/tanstack-blog-blog-post/node_modules/@tanstack/start-plugin-core/dist/esm/queue.js:38:17 {
  [cause]: Response {}
}

Node.js v24.10.0

With the nitro plugin, the error looks like this (both are imported into the vite config - you can comment either one in or out)

[prerender] Concurrency: 16
[prerender] Crawling: /
[prerender] Prerendered 0 pages:
file:///Users/arackis/Documents/git/tanstack-blog-blog-post/node_modules/@tanstack/start-plugin-core/dist/esm/prerender.js:126
            throw new Error(`Failed to fetch ${page.path}: ${res.statusText}`, {
                  ^

Error: Failed to fetch /: Internal Server Error
    at file:///Users/arackis/Documents/git/tanstack-blog-blog-post/node_modules/@tanstack/start-plugin-core/dist/esm/prerender.js:126:19
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
    at async file:///Users/arackis/Documents/git/tanstack-blog-blog-post/node_modules/@tanstack/start-plugin-core/dist/esm/queue.js:38:17 {
  [cause]: Response {}
}

Node.js v24.10.0
➜ Listening on: http://localhost:59432/ (all interfaces)

In either case, everything works perfectly once you remove the prerender option from the tanstack plugin

Your Example Website or App

https://github.com/arackaf/tanstack-blog-blog-post/tree/feature/prerender-repro

Steps to Reproduce the Bug or Issue

npm i
npm run build

Expected behavior

Should work

Screenshots or Videos

No response

Platform

• Router / Start Version: [e.g. 1.121.0]
• OS: [e.g. macOS, Windows, Linux]
• Browser: [e.g. Chrome, Safari, Firefox]
• Browser Version: [e.g. 91.1]
• Bundler: [e.g. vite]
• Bundler Version: [e.g. 7.0.0]

Additional context

No response

[kimwes]

I have this issue as well and was able to debug something that appeared to solve the issue together with claude code. Don't know if the issue is actually related to #6275 that I noticed later. There's also an additional issue when I got the prefetching to work which is that the process hangs until I press ctrl+c. Here's the findings:

Bug Report: Prerender fails with ECONNREFUSED due to race condition with Nitro

Environment

• @tanstack/react-start: 1.145.9
• nitro: 3.0.1-alpha.1
• Node.js: 24.11.1

Description

During npm run build with SPA mode enabled, the prerender step fails with "Internal Server Error" (500). The actual error is ECONNREFUSED - the prerender tries to fetch / before Nitro has started listening.

Steps to Reproduce

1. TanStack Start app with spa: { enabled: true } in vite config
2. Run npm run build
3. Prerender fails with:
   [prerender] Crawling: /
   Error: Failed to fetch /: Internal Server Error

Root Cause

In @tanstack/start-plugin-core/dist/esm/prerender.js, the prerender() function calls vite.preview() and immediately proceeds to fetch pages. However, the Nitro server (spawned by vite preview) isn't ready yet.

The console output confirms this - "Listening on: http://localhost:XXXXX/" appears AFTER the fetch error.

Test Script to Reproduce

// Immediate fetch fails, delayed fetch succeeds
const server = await vite.preview({ configFile: 'vite.config.ts', preview: { port: 0 } });
const baseUrl = server.resolvedUrls?.local[0];

// This fails with ECONNREFUSED (Nitro not ready)
await fetch(baseUrl); // 500 Internal Server Error

// Wait 1-2 seconds
await new Promise(r => setTimeout(r, 2000));

// This succeeds (Nitro is ready)
await fetch(baseUrl); // 200 OK

Workaround

Add a delay after startPreviewServer() in prerender.js:

const previewServer = await startPreviewServer(serverEnv.config);

• // Wait for Nitro server to be ready
• logger.info("Waiting for Nitro server to start...");
• await new Promise(resolve => setTimeout(resolve, 2000));
  const baseUrl = getResolvedUrl(previewServer);

Suggested Fix

Instead of a hardcoded delay, the prerender should:

1. Poll the server until it responds successfully, OR
2. Have Nitro signal when it's ready before vite.preview() resolves, OR
3. Use the existing retry mechanism with an initial delay before first fetch

And for the second issue:

Additional Issue: Server doesn't close cleanly after prerender

Description

After prerender completes successfully, the build process hangs indefinitely. The previewServer.close() call in the finally block doesn't properly terminate the Nitro server process.

Observed Behavior

[prerender] Prerendered 1 pages:
[prerender] - /

Pressing Ctrl+C triggers graceful shutdown and the build completes:

^C
Shutting down server in 3s...
Stopping preview server...
Server closed.

Location in Code

@tanstack/start-plugin-core/dist/esm/prerender.js lines 71-75:

} finally {
await previewServer.close();
}

Root Cause

The previewServer.close() closes the Vite preview server, but the spawned Nitro child process continues running, preventing the Node.js process from exiting.

Suggested Fix

After closing the preview server, ensure all child processes are terminated:

} finally {
await previewServer.close();
// Ensure Nitro child process is terminated
// Option 1: Send SIGTERM to child processes
// Option 2: Use a timeout and force exit
// Option 3: Have Nitro register a cleanup handler
}

[gurgunday]

+1

For me, just using pnpm create @tanstack/start@latest with React and nitro, removing server stuff, and then enabling prerender is enough to get this error when building