Nitro adapter fails in dev: Vite environment "ssr" is unavailable on Windows

[JosefStanek]

Hi,
I’m running into an issue with a fresh TanStack Start project using the Nitro deployment adapter.
The development server fails with:
NitroViteError: Vite environment "ssr" is unavailable
At first I thought this was caused by integrating an OpenAPI client generator, but after further testing I was able to reproduce the issue without the generator being involved.

Environment:
Windows 11
Node.js v22.17.0
npm 10.9.2
@tanstack/react-start 1.168.26
vite 8.1.0
nitro-nightly 3.0.1
Deployment adapter: Nitro (agnostic)

What works
A fresh TanStack Start project with:
Deployment adapter: None
works correctly.

What fails
A fresh TanStack Start project with:
Deployment adapter: Nitro (agnostic)
fails in development with:
NitroViteError: Vite environment "ssr" is unavailable
The stack trace points to:
node_modules/nitro/dist/runtime/internal/vite/dev-worker.mjs
Example stack:
Vite environment "ssr" is unavailable
at httpError (.../node_modules/nitro/dist/runtime/internal/vite/dev-worker.mjs:208:17)
at ViteEnvRunner.fetch (.../node_modules/nitro/dist/runtime/internal/vite/dev-worker.mjs:77:13)
at Module.fetch (.../node_modules/nitro/dist/runtime/internal/vite/dev-worker.mjs:154:12)

Things what i tried :
Clearing .vinxi
Clearing .vite
Clearing .nitro
Clearing .output
Removing and reinstalling node_modules
Running npm install again
Running the dev server outside VS Code
Creating a completely new project
Testing without generated API files
Testing without the OpenAPI generator installed
Testing with deployment adapter None
The issue persists with Nitro, but the project works without Nitro.

Is the Nitro deployment adapter currently expected to work on Windows with Node.js v22.17.0 and Vite 8?
Is there a recommended version combination for:
@tanstack/react-start
vite
nitro-nightly
@vitejs/plugin-react
or a known workaround for this error?

[barry166]

This looks like Nitro's Vite dev worker race, not the OpenAPI generator. The same Vite environment "ssr" is unavailable error is tracked upstream in nitrojs/nitro#4295: on cold dev startup the SSR entry may not finish loading before Nitro gives up after a short retry window.

So I would treat Nitro as supported for build/deploy, but flaky in dev with this version combo. Practical workarounds are: reload once after the dev server finishes warming up, pin/try a newer nitro-nightly if one contains the dev-worker fix, or use the non-Nitro dev setup locally and keep Nitro only for the deployment build. Clearing .vinxi/.nitro will not fix it if the failure is this startup race.

[JosefStanek]

Thanks for the suggestion. I investigated it further and it looks slightly different in my case.

I reproduced the issue in a completely fresh TanStack Start project with the Nitro adapter enabled. There is no hey-api integration and no generated code involved.

Here are my findings:

npm run build completes successfully.
npm run preview works correctly and SSR renders as expected.
The problem only occurs with npm run dev.
If I disable/comment out the Nitro adapter, npm run dev works normally.

I also tried the proposed workaround by increasing the retry loop in dev-worker.mjs from 5 attempts to 600 attempts. Unfortunately, it did not resolve the issue. Instead, the request eventually times out with:

transport invoke timed out after 60000ms
event: vite:invoke
name: getBuiltins

This makes me think the problem is not simply that the SSR entry takes longer than the retry window. It looks like the Nitro dev worker never successfully initializes the SSR environment (or the Vite worker communication gets stuck), while the production build works correctly.

Environment:

TanStack Start 1.168.26
Nitro nightly 3.0.1-20260629-191608-8b0b9576
Vite 8.1.0
Node.js 22.17.0
Windows 11

[MILLERMARRU]

This matches a known, still open Nitro bug rather than anything specific to the OpenAPI generator or the project setup. nitrojs/nitro#4295 documents the exact same error and stack trace (ViteEnvRunner.fetch throwing Vite environment "ssr" is unavailable from dev-worker.mjs).

The root cause described there: ViteEnvRunner.fetch waits for the SSR entry module to finish importing, but only retries 5 times with exponential backoff, roughly 100+200+400+800+1600ms, about 3.1 seconds total. On a project where the SSR entry's first cold transform takes longer than that (larger dependency graphs, slower disk access, which Windows tends to be more prone to than macOS/Linux for cold node_modules reads), the wait gives up before the entry is ready and throws instead of retrying further.

That issue is still open with no merged fix as of the most recent nitro-nightly builds, so upgrading nitro-nightly alone likely won't resolve it yet. Two practical paths while it's unresolved:

Patch the retry loop locally with patch-package or pnpm patch, replacing the fixed 5-iteration backoff in node_modules/nitro/dist/runtime/internal/vite/dev-worker.mjs with a longer, fixed-interval retry (the issue itself proposes something like 600 iterations of 50ms, about 30 seconds ceiling, which still resolves instantly in the common warm case).

Or keep Deployment adapter: None for local development, since that's already confirmed working, and only exercise the Nitro adapter for builds/deploys until the upstream fix lands.

Worth noting nitro-nightly is exactly what it says, a rolling nightly channel with several builds published per day, so there isn't really a stable known-good version pin to recommend today for this combination.