Dev server breaks behind reverse proxy since v1.167.17 (virtual module \0-prefix in browser URL)

[TimElschner]

Description

Since @tanstack/react-start@1.167.17 (PR #7144), the dev server breaks when accessed through a reverse proxy (Cloudflare, nginx, Caddy, Pangolin). The browser receives 400 Bad Request for the new #tanstack-start-plugin-adapters virtual module.

Reproduction

1. Set up a TanStack Start app with @tanstack/react-start@1.167.17+
2. Access the dev server through any reverse proxy (e.g., Cloudflare Tunnel, nginx, Caddy)
3. The app fails to load

Works: Direct access via localhost:3000
Breaks: Access through reverse proxy → https://myapp.example.com

Browser console errors

GET https://myapp.example.com/@id/__x00__%23tanstack-start-plugin-adapters net::ERR_ABORTED 400 (Bad Request)

Uncaught (in promise) TypeError: Failed to fetch dynamically imported module:
  https://myapp.example.com/@id/virtual:tanstack-start-client-entry

Root Cause

PR #7144 introduced a new virtual module #tanstack-start-plugin-adapters in packages/start-plugin-core/src/vite/serialization-adapters-plugin.ts. This module is:

1. Resolved via resolveId/load hooks (producing a \0-prefixed ID)
2. Imported by client-side code in hydrateStart.ts

Vite encodes the \0 prefix as __x00__ in browser-facing URLs, resulting in:

/@id/__x00__%23tanstack-start-plugin-adapters

Reverse proxies and WAFs (Cloudflare, nginx, Caddy) correctly reject URLs containing null-byte representations as a security measure (HTTP anomaly detection).

Why other virtual modules work

The existing virtual modules (#tanstack-start-entry, #tanstack-router-entry) use resolve.alias in the Vite config, mapping to real filesystem paths. They never become \0-prefixed, so no /@id/__x00__ URL appears in the browser.

#tanstack-start-server-fn-resolver does use resolveId/load, but it's only loaded server-side (SSR), never requested by the browser.

#tanstack-start-plugin-adapters is the first virtual module that uses resolveId/load AND is imported by client-side code.

Suggested Fix

Handle #tanstack-start-plugin-adapters the same way as #tanstack-start-entry — via resolve.alias pointing to a real file (e.g., packages/start-client-core/src/fake-entries/plugin-adapters.ts), instead of the resolveId/load virtual module pattern.

Environment

• @tanstack/react-start: 1.167.28 (broken), 1.167.16 (last working)
• Vite: 7.3.2
• Reverse proxy: Pangolin (Caddy-based) + Cloudflare DNS proxy
• OS: Windows 11 (dev), Linux (proxy)
• Browser: Chrome

Workaround

Pin @tanstack/react-start to 1.167.16 and @tanstack/react-router to 1.168.10.

[TimElschner]

Additional context from source code analysis:

Looking at `packages/start-plugin-core/src/vite/serialization-adapters-plugin.ts`, there's already a comment acknowledging the browser URL issue:

```ts
// Encode '#' as '%23' in the resolved ID to avoid browser treating it as URL fragment.
// The browser requests /@id/x00%23tanstack-start-plugin-adapters instead of
// /@id/x00#tanstack-start-plugin-adapters (which would truncate at #).
```

The `#` → `%23` encoding was handled, but the `\0` prefix (which Vite encodes as `x00` in browser-facing URLs) was not considered. Reverse proxies and WAFs (Cloudflare, nginx, Caddy) reject URLs containing null-byte representations as a security measure.

Why `resolveId`/`load` is used instead of `resolve.alias`: The plugin needs to return different code depending on the environment (client vs. server), which `resolve.alias` cannot do. A possible fix could be to use a custom Vite middleware that serves this module directly, bypassing the `\0`-prefixed virtual module ID for browser requests.

[schiller-manuel]

where is the __x00__ lost here with the reverse proxy? can you please provide a complete reproducer project as a git repo?

[TimElschner]

Did further investigation. Tested the URL /@id/__x00__%23tanstack-start-plugin-adapters (on a minimal TanStack Start app pinned to @tanstack/react-start@1.167.28) against multiple proxies directly via curl:

Proxy	Config	Result
Vite dev server (direct)	—	200 OK (535 bytes of JS)
Caddy 2	default reverse_proxy	200 OK
nginx	default proxy_pass	200 OK
Traefik v3	default loadBalancer	200 OK
OWASP ModSecurity CRS (nginx)	BLOCKING_PARANOIA=4	200 OK
Cloudflare (production)	proxy ON	400 Bad Request

So the __x00__ in the URL is not lost in standard reverse proxies — they all pass it through correctly. The 400 in our environment is produced by Cloudflare's proprietary WAF / HTTP anomaly detection, which I cannot reproduce locally.

That said, the underlying concern stands: shipping a Vite-internal \0-prefixed module ID (encoded as __x00__) as a browser-facing URL is fragile because:

• Cloudflare's proxy mode is used by millions of sites and blocks this pattern
• It's generally considered a Vite internal implementation detail that shouldn't leak to browser URLs
• Other virtual modules in this codebase (#tanstack-start-entry, #tanstack-router-entry) use resolve.alias and don't have this issue

Since I can't produce a failing local reproducer (Cloudflare WAF is closed-source), I'll stop here unless you'd like me to package the test matrix above into a runnable docker compose repo for documentation purposes.

[schiller-manuel]

pasting a lot of AI output here is not helping much. if only cloudflare proxy is failing, better raise the issue there.

[fcannizzaro]

@schiller-manuel This happens also on local reverse proxy (for HTTPS localhost).

I have the same issue with traefik, where running http://localhost:3000 works fine while the same dev server behind the proxy give the error:

Uncaught (in promise) TypeError: Failed to fetch dynamically imported module: https://appname.localhost/@id/virtual:tanstack-start-client-entry

The url that the browser tries to load is https://appname.localhost/@id/__x00__%23tanstack-start-plugin-adapters url. So this is not a cloudflare only issue.

[schiller-manuel]

@fcannizzaro can you please open a new GitHub issue including a complete minimal reproducer project as a git repo?