# Known Issue: web-next Production Build Fails

**Status:** Open | **Severity:** Low (dev mode unaffected)
**Affects:** `pnpm build` (production) for `apps/web-next` only
**Does NOT affect:** `pnpm dev`, login, dashboard, spawning new projects

## Root Cause

next-intl "without-i18n-routing" setup causes legacy error pages
(`/404`, `/_error`) to fail static prerender on Next.js 15 production builds.
Next.js 16 has a separate `/_global-error` `useContext` regression.
Both are upstream framework bugs, not template bugs.

Verified across multiple combinations during spawn-test investigation:

| Next version                                                                    | Behavior                                                                                                                                                                                     |
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 15.5.18 (current)                                                               | `<Html> outside _document` on `/404`/`/500`/`/_error` — Next's own internal `_document` chunk. No app fix.                                                                                   |
| 15.1.8 (pinned)                                                                 | Same `<Html>` bug, masked by earlier `useContext` null on pages with `useTransition`.                                                                                                        |
| 16.2.6 + next-intl 4.13 + i18n routing + `force-dynamic` + root `not-found.tsx` | `<Html>` gone; real pages prerender; **but `/_global-error` static prerender fails with `useContext` null in Next's own `next_dist` chunk** — reproduces even with the default global-error. |

No `next/document` import exists anywhere in the app or its transpiled deps.
No Partytown usage. No OTEL instrumentation. The trigger is purely framework-level.

## Workaround

Use `pnpm dev` for all development. Production deployment of web-next
should use Vercel (which handles the error page differently) or
wait for Next.js 15.x patch.

The primary frontend (`apps/web-angular`) is unaffected and builds cleanly.
Day-1 criteria (per `CLAUDE.md` §11 and `GENESIS.md` §3) use `pnpm dev`,
not `pnpm build`, for the developer experience — that path is fully green.

## Resolution Path

- **Path A:** Wait for Next 15.5.x patch fixing `<Html>` legacy export bug
- **Path B:** Migrate web-next to next-intl i18n routing (`app/[locale]/`)
  as a deliberate v1.1.0 upgrade. The migration was prototyped and the diff
  is documented; blocker is the Next 16 `/_global-error` regression that
  must be resolved upstream (or pinned to a working Next 16 patch).

## Tracking

Opened: 2026-05-29 | Target fix: v1.1.0
