Boot fails with "Unable to preload CSS" when main's CSS preload fails; chunk reload guard isn't registered yet#26437

What happened

I created a guest share link in the desktop app and opened it in Firefox on the same Mac to check that it worked. The page showed "T3 Code failed to start" with:

The same error appeared again on a reload. A load about 25 minutes later worked.

Diagnosis

Why a single failed request ends at the boot error screen. apps/web/src/bootstrap.ts runs import("./main"). The bundler's preload helper in the built entry chunk (index-*.js) first adds a <link rel="stylesheet"> for main-*.css. When that link fires error, the helper dispatches vite:preloadError. Nothing calls preventDefault(), so the helper rethrows. bootstrap.ts catches the error and calls showBootError.

Why the existing auto-reload doesn't help. apps/web/src/main.tsx registers a vite:preloadError listener that calls reloadOnceForChunkLoadError(). The guard's comment says it exists for this case: "one reload fetches the fresh index". But that listener lives in main.tsx, the very module whose preload failed, so it isn't registered yet. showBootError has no special handling for chunk or preload errors either. The result: any failure to load main-*.js or main-*.css goes straight to the boot error screen with no automatic retry. Lazy route chunks are covered by the guard.

What triggered it here. The stylesheet request was lost inside the managed relay client (cloudflared) and never reached the local server:

• Server trace: the server received the /guest page request, index-*.js, main-*.js and about 160 other /assets/*.js modules through the relay host, all within about 1 s and all returning 200. There is no request for /assets/main-ufMFs_gT.css.
• cloudflared counters: cloudflared's /metrics show total_requests 433 but request_errors 6. Its count of responses by status code (221×200, 205×304, 1×403) matches exactly what the server trace recorded on the relay host over the same period (427 requests). So 6 requests failed inside cloudflared before reaching the origin.
• Per-request detail is lost: ManagedEndpointRuntime passes cloudflared's output to the logger at warning level, but none of it lands in server.trace.ndjson. The 6 failures can't be matched to individual requests after the fact.

Not confirmed: why the reload failed too. A normal reload about 20 minutes later failed again. The server received only /guest, and again no CSS request. Two possible causes, neither confirmed:

• the tunnel failed the CSS request again; or
• the browser reused the failed response.

The relay serves /assets/* with cache-control: max-age=14400, while the local server sends no-cache. That includes the text/html single-page-app fallback page for asset paths that don't exist. A later load that fetched the CSS fresh booted normally.

Suggested direction. Register the vite:preloadError → reloadOnceForChunkLoadError() handler in bootstrap.ts before import("./main"). Alternatively, have showBootError do the one-time reload for preload and dynamic-import errors. Separately, persisting cloudflared request errors to the trace would make relay failures visible.

No commits on main touch bootstrap.ts, main.tsx or chunkReloadGuard.ts after v0.1.3.

Steps to reproduce

The failure here was transient:

1. On desktop app 0.1.3 with T3 Connect (managed relay) enabled, create a guest share link.
2. Open it in Firefox. The first, cold load sends about 160 parallel module requests through the relay.
3. If the main-*.css request fails in the tunnel, the boot error screen appears and no automatic reload happens.

To hit the boot-error path deterministically, which should work but was not run during triage: open the web app with the main-*.css request blocked, for example with Firefox DevTools → Network → right-click the request → Block URL, then reload. Expected: one automatic reload, as for lazy chunks. Actual (from reading the code): "T3 Code failed to start" straight away.

Version

0.1.3 (desktop app, stable channel; web UI served by that app's server through the T3 Connect relay)

Environment

macOS 27.0 (Apple Silicon), Firefox 158; desktop app 0.1.3 with managed cloudflared 2026.10.4. Triage CLI 0.1.3.

Evidence

Related issues

#10613 shows the same failure type (a code bundle that fails to load ends at the error screen) but has a different trigger and surface: a desktop channel switch, a route chunk over t3code://. Here it is the main chunk's CSS on the web surface over the relay, a case the reload guard can't reach because its listener lives in main.tsx.

Fix applied or workaround

Nothing was changed on the machine; a later load fetched the CSS and booted normally. If it recurs, a hard reload (Cmd+Shift+R) forces a fresh fetch of the assets.

Filed by

Claude Opus 5.5 (claude-opus-5-5) in Claude Code, via t3 triage