Skip to content

fix(pages-router): render app/not-found for a hybrid Pages notFound - #3771

Open
AhmedElBanna80 wants to merge 6 commits into
cloudflare:mainfrom
AhmedElBanna80:fix/pages-notfound-app-not-found
Open

AhmedElBanna80 wants to merge 6 commits into
cloudflare:mainfrom
AhmedElBanna80:fix/pages-notfound-app-not-found

Conversation

@AhmedElBanna80

Copy link
Copy Markdown
Contributor

Closes #3428.

In a hybrid app, a Pages route that resolves to notFound (gSP/gSSP notFound, or a fallback: false miss) renders pages/404. Next.js renders app/not-found instead: with the app dir enabled, renderErrorToResponseImpl tries /_not-found before /404, and pages-handler.ts sends notFound through render404.

Fixtures from test/e2e/app-dir/not-found-with-pages-i18n and pages-router-app-not-found, built on 1.0.1:

Request before next start / this PR
/app-dir/foo (App notFound()) App not-found App not-found
/, /foo (Pages notFound) pages/404 App not-found
/pages-route/x (no pages/404) Pages _error App not-found

How:

  • pages-page-handler.ts: new markNotFound render option. With it, a document 404 from a notFound result gets x-vinext-pages-not-found. Data requests and pages that set their own 404 status aren't marked.
  • app-pages-bridge.ts: passes markNotFound for document renders, and drops the header if middleware sets it.
  • app-rsc-handler.ts: the unmatched-route not-found render moves into renderAppNotFound(). When the Pages response is marked, renderPagesForMatchKind renders it instead; otherwise the marker is stripped. Doing it in the request handler covers both the single-stage path and the split hybrid-pages → app-not-found path, and later rewrites don't run once a Pages route has matched.
  • Cache-Control: the 404 keeps the source route's value (s-maxage=1, ... for revalidate: 1). Next sets it from the notFound revalidate before render404, and the App render only sets Cache-Control when none is present.

The marker follows the x-vinext-special-error-status pattern. If you'd prefer a different shape, I'm happy to change it.

Dev isn't covered: dev-server.ts renders hybrid Pages separately and still shows pages/404. I can do that in a follow-up.

Tests: tests/hybrid-pages-not-found.test.ts builds the fixture and checks gSP/gSSP notFound, fallback: false, a non-default locale, Cache-Control, the cookies() content inside the not-found, and that found routes still render. Unit tests cover the handler (single and split stage), the bridge, and the Pages handler. Reverting any one of the three source files makes them fail.

In an app with both app/ and pages/, a Pages route that resolves to notFound
(getStaticProps/getServerSideProps notFound, or a fallback: false miss)
rendered pages/404. Next.js renders the App Router not-found in that case:
with the app directory enabled, renderErrorToResponseImpl looks up
/_not-found first and only falls back to /404 when it is missing.

The hybrid bridge now asks the Pages renderer to mark a document 404 that
came from a notFound result (x-vinext-pages-not-found). The App request
stage consumes the marker and renders its not-found in place, keeping the
source route's Cache-Control as pages-handler.ts does before render404.
Middleware headers can't set the marker, and a page that renders itself
with a 404 status is not marked.

Production only; the dev server renders hybrid Pages through its own path.

Closes cloudflare#3428
@pkg-pr-new

pkg-pr-new Bot commented Oct 8, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

@vinext/cloudflare

npm i https://pkg.pr.new/@vinext/cloudflare@3771

create-vinext-app

npm i https://pkg.pr.new/create-vinext-app@3771

@vinext/types

npm i https://pkg.pr.new/@vinext/types@3771

vinext

npm i https://pkg.pr.new/vinext@3771

@cloudflare/workers-response-store

npm i https://pkg.pr.new/@cloudflare/workers-response-store@3771

commit: 6fbba36

@github-actions

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

Performance benchmarks

Compared 6fbba36 against base 8659957 using alternating same-runner rounds. Next.js was unchanged and skipped.

1 improved · 0 regressed · 6 within ±1.5%

Scenario Framework Baseline Current Change
Client bundle size (gzip) vinext 152.3 KB 152.3 KB ⚫ 0.0%
Client entry size (gzip) vinext 140.6 KB 140.6 KB ⚫ 0.0%
Dev server cold start vinext 2.85 s 2.82 s ⚫ -1.1%
Dev server cold start (large Pages Router app) vinext 23.94 s 23.57 s 🟢 -1.5%
Production build time vinext 3.45 s 3.41 s ⚫ -1.0%
RSC entry closure size (gzip) vinext 142.6 KB 142.7 KB ⚫ +0.1%
Server bundle size (gzip) vinext 250.2 KB 250.3 KB ⚫ +0.1%

View detailed results and traces

🟢 improvement · 🔴 regression · ⚫ change below 1.5% · paired base/head

@AhmedElBanna80

Copy link
Copy Markdown
Contributor Author

CI: the one failing integration test (app-router-production-server, "lets a concrete Pages data route win a middleware rewrite over an App catch-all") also fails on main in runs 37763690664 and 37759531306.

…arker, HEAD and the default not-found

Cover the data-request exclusion, middleware being unable to set the
x-vinext-pages-not-found marker, HEAD, and an app without app/not-found
(Next.js adds its built-in /_not-found, so pages/404 is not reached).

Two redundant pieces go: a header delete that ran on the App response,
which never carries the marker, and the `!isDataReq` clause on the
marking branch. A data request's notFound already resolves to a JSON
response before that branch (buildPagesNotFoundResult), so the clause
could not be reached; the unit test now pins that instead.
@AhmedElBanna80

Copy link
Copy Markdown
Contributor Author

Pushed a follow-up commit that tightens the tests and drops two redundant bits of code.

Tests added: /_next/data requests stay JSON 404s (no marker), a middleware that sets x-vinext-pages-not-found on a page that renders fine can't turn it into a 404, HEAD, and an app with no app/not-found.

That last case matches Next.js: with the app directory enabled it adds the built-in /_not-found entry whenever the app has pages (build/route-discovery.ts), and renderErrorToResponseImpl looks it up before /404, so pages/404 isn't reached there either.

Removed: a header delete in withPagesNotFoundCacheControl (it ran on the App response, which never carries the marker) and the !isDataReq clause on the marking branch. A data request's notFound already becomes a JSON response in buildPagesNotFoundResult before that branch, so the clause was unreachable. Dropping it left every test green, so I removed it and pinned the data-request behaviour with a handler test instead.

# Conflicts:
#	packages/vinext/src/server/app-rsc-handler.ts
@clanky-the-clanker

Copy link
Copy Markdown

This pull request was not reviewed automatically because its author does not have write access to this repository. A maintainer with write access can start a review by commenting clanky review (or clanker review or @clanky-the-clanker review), optionally followed by instructions (e.g. clanky review focus on the retry logic).

# Conflicts:
#	packages/vinext/src/server/pages-page-handler.ts
…p-not-found

# Conflicts:
#	packages/vinext/src/server/app-rsc-handler.ts
#	packages/vinext/src/server/headers.ts
@AhmedElBanna80

Copy link
Copy Markdown
Contributor Author

@james-elicx Could you take a look when you have a moment? CI is green and the branch merges cleanly. This is one of five related PRs (#3686, #3741, #3759, #3768, #3771); I'm happy to rebase or split any of them if that makes reviewing easier. Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Hybrid app: Pages notFound renders pages/404 instead of app/not-found

1 participant