Unverified Commit 0950e8ae authored by dan's avatar dan Committed by GitHub

Return plain text 404 for non-document requests to unknown paths (#95930)

Not sure if there's any downside to this.

Currently, there are situations when a browser requests something in a
particular format:

- Favicons
- Manifest icons
- `<img>` with broken `src`
- Wrong `<link>`s
- `new Worker()`

These requests have a `Sec-Fetch-Dest` header which can definitely
exclude things that can't be HTML. My proposal is to not return the HTML
for them (even in dev) so that this doesn't waste time in case rendering
the root layout is slow or expensive. Less work for the server, whether
dev or prod.

I believe this was happening in dev, and in prod if rendering
`not-found` requires something dynamic (e.g. in the root layout). And
for static self-hosted, I believe it would respond with static HTML.

After this change, we don't render the HTML.

## Before

Image in manifest hits the real `/not-found` route and runs application
code:

<img width="1055" height="639" alt="Screenshot 2026-07-19 at 00 23 01"
src="https://github.com/user-attachments/assets/869f85f8-a009-4266-a345-74e3342adb41"
/>

Notice 404 at the end with 2 seconds in application code.

## After

Image in manifest is still 404 but doesn't hit any app code.

<img width="1033" height="696" alt="Screenshot 2026-07-19 at 00 21 17"
src="https://github.com/user-attachments/assets/3a1817b4-f050-45c0-93ca-0507cf9de803"
/>

It's maybe a bit weird it doesn't show in the terminal log. In that
sense it's like `/_next/static/` because it's handled at an earlier
layer. Maybe we could still log it but it would have to happen from a
different place, and also breaks consistency, so I opted with keeping it
hidden.

---

I can't see any coherent arguments for why this should reach the app
render so this should be OK?
parent b1713c85
......@@ -31,6 +31,8 @@ import {
} from '../../server/base-http/node' with { 'turbopack-transition': 'next-server-utility' }
import { checkIsAppPPREnabled } from '../../server/lib/experimental/ppr' with { 'turbopack-transition': 'next-server-utility' }
import { isRSCRequestHeader } from '../../server/lib/is-rsc-request' with { 'turbopack-transition': 'next-server-utility' }
import { isNonHtmlSecFetchDest } from '../../server/lib/is-non-html-sec-fetch-dest' with { 'turbopack-transition': 'next-server-utility' }
import { UNDERSCORE_NOT_FOUND_ROUTE } from '../../shared/lib/entry-constants' with { 'turbopack-transition': 'next-server-utility' }
import {
getFallbackRouteParams,
getPlaceholderFallbackRouteParams,
......@@ -305,6 +307,25 @@ export async function handler(
const isPossibleServerAction = getIsPossibleServerAction(req)
// For subresource requests (e.g. images or fonts), return plain text 404
// instead of rendering the not-found route.
if (
normalizedSrcPage === UNDERSCORE_NOT_FOUND_ROUTE &&
(req.method === 'GET' || req.method === 'HEAD') &&
!isRSCRequest &&
isNonHtmlSecFetchDest(req.headers['sec-fetch-dest'])
) {
res.statusCode = 404
res.setHeader(
'Cache-Control',
'private, no-cache, no-store, max-age=0, must-revalidate'
)
res.setHeader('Content-Type', 'text/plain; charset=utf-8')
res.end('Not Found')
ctx.waitUntil?.(Promise.resolve())
return null
}
/**
* If the route being rendered is an app page, and the ppr feature has been
* enabled, then the given route _could_ support PPR.
......
......@@ -49,6 +49,7 @@ import * as path from 'path'
import { format as formatUrl } from 'url'
import { formatHostname } from './lib/format-hostname'
import { isRSCRequestHeader } from './lib/is-rsc-request'
import { isNonHtmlSecFetchDest } from './lib/is-non-html-sec-fetch-dest'
import {
APP_PATHS_MANIFEST,
NEXT_BUILTIN_DOCUMENT,
......@@ -2354,6 +2355,21 @@ export default abstract class Server<
// we need to ensure the status code if /404 is visited directly
if (is404Page && !isNextDataRequest && !isRSCRequest) {
res.statusCode = 404
// For subresource requests (e.g. images or fonts), return plain text
// 404 instead of rendering the not-found route.
if (
(req.method === 'GET' || req.method === 'HEAD') &&
isNonHtmlSecFetchDest(req.headers['sec-fetch-dest'])
) {
res.setHeader(
'Cache-Control',
'private, no-cache, no-store, max-age=0, must-revalidate'
)
res.setHeader('Content-Type', 'text/plain; charset=utf-8')
res.body('Not Found').send()
return null
}
}
// ensure correct status is set when visiting a status page
......
/**
* `Sec-Fetch-Dest` values for subresource requests that can never render an
* HTML response. Excludes destinations that can display HTML (`document`,
* `iframe`, etc.) and `empty` (`fetch()`/XHR, including RSC requests).
*/
const NON_HTML_SEC_FETCH_DESTS = new Set([
'audio',
'audioworklet',
'font',
'image',
'json',
'manifest',
'paintworklet',
'report',
'script',
'serviceworker',
'sharedworker',
'style',
'track',
'video',
'webidentity',
'worker',
'xslt',
])
export function isNonHtmlSecFetchDest(
value: string | string[] | null | undefined
): boolean {
return typeof value === 'string' && NON_HTML_SEC_FETCH_DESTS.has(value)
}
......@@ -26,6 +26,7 @@ import { removePathPrefix } from '../../shared/lib/router/utils/remove-path-pref
import setupCompression from 'next/dist/compiled/compression'
import { signalFromNodeResponse } from '../web/spec-extension/adapters/next-request'
import { isPostpone } from './router-utils/is-postpone'
import { isNonHtmlSecFetchDest } from './is-non-html-sec-fetch-dest'
import { parseUrl as parseUrlUtil } from '../../shared/lib/router/utils/parse-url'
import {
......@@ -726,6 +727,18 @@ export async function initialize(opts: {
return null
}
// For subresource requests (e.g. images or fonts), return plain text
// 404 instead of rendering the not-found route.
if (
(req.method === 'GET' || req.method === 'HEAD') &&
isNonHtmlSecFetchDest(req.headers['sec-fetch-dest'])
) {
res.statusCode = 404
res.setHeader('Content-Type', 'text/plain; charset=utf-8')
res.end('Not Found')
return null
}
// Short-circuit favicon.ico serving so that the 404 page doesn't get built as favicon is requested by the browser when loading any route.
if (opts.dev && !matchedOutput && parsedUrl.pathname === '/favicon.ico') {
res.statusCode = 404
......
import { ReactNode, Suspense } from 'react'
import { connection } from 'next/server'
async function Dynamic() {
await connection()
return null
}
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>
<Suspense>
<Dynamic />
</Suspense>
{children}
</body>
</html>
)
}
export default function NotFound() {
console.log('__not-found-component-rendered__')
return <h1>custom not found page</h1>
}
export default function Page() {
return <p>hello world</p>
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {}
module.exports = nextConfig
import { isNextDeploy, nextTestSetup } from 'e2e-utils'
describe('not-found-non-document-dynamic', () => {
const { next } = nextTestSetup({
files: __dirname,
})
it('returns a plain text 404 for subresource requests to unknown paths', async () => {
const outputIndex = next.cliOutput.length
const res = await next.fetch('/web-app-manifest-192x192.png', {
headers: {
accept: 'image/avif,image/webp,image/png,image/svg+xml,image/*;q=0.8',
'sec-fetch-dest': 'image',
'sec-fetch-mode': 'no-cors',
'sec-fetch-site': 'same-origin',
},
})
expect(res.status).toBe(404)
if (isNextDeploy && process.env.__NEXT_CACHE_COMPONENTS) {
// With cache components the not-found route is prerendered, and the
// deployed routing layer serves prerenders without invoking Next.js.
// TODO: It might be good to align the CDN behavior so subresource
// requests to unknown paths get the plain text 404 when deployed too.
expect(res.headers.get('content-type')).toContain('text/html')
} else {
expect(res.headers.get('content-type')).toContain('text/plain')
expect(res.headers.get('cache-control')).toBe(
'private, no-cache, no-store, max-age=0, must-revalidate'
)
expect(await res.text()).toBe('Not Found')
}
if (!isNextDeploy) {
expect(next.cliOutput.slice(outputIndex)).not.toContain(
'__not-found-component-rendered__'
)
}
})
it('renders the not-found page for document requests to unknown paths', async () => {
const res = await next.fetch('/does-not-exist', {
headers: {
accept:
'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
'sec-fetch-dest': 'document',
'sec-fetch-mode': 'navigate',
'sec-fetch-site': 'none',
},
})
expect(res.status).toBe(404)
expect(res.headers.get('content-type')).toContain('text/html')
expect(await res.text()).toContain('custom not found page')
})
it('renders the not-found page for fetch requests to unknown paths', async () => {
const res = await next.fetch('/does-not-exist', {
headers: {
'sec-fetch-dest': 'empty',
'sec-fetch-mode': 'cors',
'sec-fetch-site': 'same-origin',
},
})
expect(res.status).toBe(404)
expect(res.headers.get('content-type')).toContain('text/html')
expect(await res.text()).toContain('custom not found page')
})
})
import { ReactNode } from 'react'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
export default function NotFound() {
console.log('__not-found-component-rendered__')
return <h1>custom not found page</h1>
}
import Link from 'next/link'
export default function Page() {
return (
<>
<p>hello world</p>
<Link href="/does-not-exist" id="link-to-missing">
go to missing page
</Link>
</>
)
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {}
module.exports = nextConfig
import { isNextDeploy, nextTestSetup } from 'e2e-utils'
import { retry } from 'next-test-utils'
describe('not-found-non-document', () => {
const { next } = nextTestSetup({
files: __dirname,
})
it('returns a plain text 404 for subresource requests to unknown paths', async () => {
const outputIndex = next.cliOutput.length
const res = await next.fetch('/web-app-manifest-192x192.png', {
headers: {
accept: 'image/avif,image/webp,image/png,image/svg+xml,image/*;q=0.8',
'sec-fetch-dest': 'image',
'sec-fetch-mode': 'no-cors',
'sec-fetch-site': 'same-origin',
},
})
expect(res.status).toBe(404)
if (isNextDeploy) {
// The build emits a prerendered not-found page, and the deployed
// routing layer serves it without invoking Next.js.
// TODO: It might be good to align the CDN behavior so subresource
// requests to unknown paths get the plain text 404 when deployed too.
expect(res.headers.get('content-type')).toContain('text/html')
} else {
expect(res.headers.get('content-type')).toContain('text/plain')
expect(res.headers.get('cache-control')).toBe(
'private, no-cache, no-store, max-age=0, must-revalidate'
)
expect(await res.text()).toBe('Not Found')
expect(next.cliOutput.slice(outputIndex)).not.toContain(
'__not-found-component-rendered__'
)
}
})
it('returns a plain text 404 for font and manifest requests to unknown paths', async () => {
for (const dest of ['font', 'manifest']) {
const res = await next.fetch(`/missing-${dest}`, {
headers: {
'sec-fetch-dest': dest,
'sec-fetch-mode': 'no-cors',
'sec-fetch-site': 'same-origin',
},
})
expect(res.status).toBe(404)
if (isNextDeploy) {
// The build emits a prerendered not-found page, and the deployed
// routing layer serves it without invoking Next.js.
// TODO: It might be good to align the CDN behavior so subresource
// requests to unknown paths get the plain text 404 when deployed too.
expect(res.headers.get('content-type')).toContain('text/html')
} else {
expect(res.headers.get('content-type')).toContain('text/plain')
expect(res.headers.get('cache-control')).toBe(
'private, no-cache, no-store, max-age=0, must-revalidate'
)
expect(await res.text()).toBe('Not Found')
}
}
})
it('renders the not-found page for document requests to unknown paths', async () => {
const res = await next.fetch('/does-not-exist', {
headers: {
accept:
'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
'sec-fetch-dest': 'document',
'sec-fetch-mode': 'navigate',
'sec-fetch-site': 'none',
},
})
expect(res.status).toBe(404)
expect(res.headers.get('content-type')).toContain('text/html')
expect(await res.text()).toContain('custom not found page')
})
it('renders the not-found page for requests without sec-fetch-dest', async () => {
const res = await next.fetch('/does-not-exist')
expect(res.status).toBe(404)
expect(res.headers.get('content-type')).toContain('text/html')
expect(await res.text()).toContain('custom not found page')
})
it('renders the not-found page for fetch requests to unknown paths', async () => {
const res = await next.fetch('/does-not-exist', {
headers: {
'sec-fetch-dest': 'empty',
'sec-fetch-mode': 'cors',
'sec-fetch-site': 'same-origin',
},
})
expect(res.status).toBe(404)
expect(res.headers.get('content-type')).toContain('text/html')
expect(await res.text()).toContain('custom not found page')
})
it('renders the not-found page on client navigation to unknown paths', async () => {
const browser = await next.browser('/')
await browser.elementByCss('#link-to-missing').click()
await retry(async () => {
expect(await browser.elementByCss('h1').text()).toBe(
'custom not found page'
)
})
})
})
// Mimics how deployment platforms invoke the compiled not-found route entry:
// the adapter launcher requires the route's page.js and calls its handler
// export with minimal-mode request metadata.
const http = require('http')
const path = require('path')
require('next/dist/build/adapter/setup-node-env.external')
const dir = process.cwd()
const port = Number(process.env.PORT)
const mod = require(path.join(dir, '.next/server/app/_not-found/page.js'))
http
.createServer((req, res) => {
Promise.resolve(
mod.handler(req, res, {
waitUntil: undefined,
requestMeta: {
minimalMode: true,
relativeProjectDir: '.',
initURL: `https://localhost${req.url}`,
},
})
).catch((err) => {
console.error('handler error', err)
if (!res.writableEnded) {
res.statusCode = 500
res.end('internal error')
}
})
})
.listen(port, () => console.log('adapter launcher ready'))
import { ReactNode, Suspense } from 'react'
import { connection } from 'next/server'
async function Dynamic() {
await connection()
return null
}
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>
<Suspense>
<Dynamic />
</Suspense>
{children}
</body>
</html>
)
}
export default function NotFound() {
console.log('__not-found-component-rendered__')
return <h1>custom not found page</h1>
}
export default function Page() {
return <p>hello world</p>
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {}
module.exports = nextConfig
import { spawn, type ChildProcess } from 'child_process'
import path from 'path'
import { nextTestSetup } from 'e2e-utils'
import { findPort, retry } from 'next-test-utils'
describe('not-found-non-document-adapter', () => {
const { next, skipped } = nextTestSetup({
files: __dirname,
skipDeployment: true,
skipStart: true,
})
if (skipped) {
return
}
let launcher: ChildProcess
let port: number
beforeAll(async () => {
await next.build()
port = await findPort()
launcher = spawn('node', [path.join(next.testDir, 'adapter-launcher.js')], {
cwd: next.testDir,
env: { ...process.env, PORT: String(port) },
stdio: 'pipe',
})
let output = ''
launcher.stdout?.on('data', (chunk) => (output += chunk))
launcher.stderr?.on('data', (chunk) => (output += chunk))
await retry(async () => {
expect(output).toContain('adapter launcher ready')
})
})
afterAll(() => {
launcher?.kill()
})
it('returns a plain text 404 for subresource requests', async () => {
const res = await fetch(`http://localhost:${port}/missing-image.png`, {
headers: {
'x-matched-path': '/_not-found',
'sec-fetch-dest': 'image',
'sec-fetch-mode': 'no-cors',
},
})
expect(res.status).toBe(404)
expect(res.headers.get('content-type')).toContain('text/plain')
expect(res.headers.get('cache-control')).toBe(
'private, no-cache, no-store, max-age=0, must-revalidate'
)
expect(await res.text()).toBe('Not Found')
})
it('renders the not-found page for document requests', async () => {
const res = await fetch(`http://localhost:${port}/does-not-exist`, {
headers: {
'x-matched-path': '/_not-found',
accept:
'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
'sec-fetch-dest': 'document',
'sec-fetch-mode': 'navigate',
},
})
expect(res.headers.get('content-type')).toContain('text/html')
expect(await res.text()).toContain('custom not found page')
})
it('serves the not-found RSC payload for router requests', async () => {
const res = await fetch(`http://localhost:${port}/does-not-exist`, {
headers: {
'x-matched-path': '/_not-found',
rsc: '1',
},
})
expect(res.headers.get('content-type')).toContain('text/x-component')
expect(await res.text()).not.toBe('Not Found')
})
it('renders the not-found page for requests without sec-fetch-dest', async () => {
const res = await fetch(`http://localhost:${port}/whatever.bin`, {
headers: {
'x-matched-path': '/_not-found',
},
})
expect(res.headers.get('content-type')).toContain('text/html')
expect(await res.text()).toContain('custom not found page')
})
})
import { nextTestSetup } from 'e2e-utils'
describe('not-found-non-document-minimal', () => {
const { next } = nextTestSetup({
files: __dirname,
// This test synthesizes an adapter invocation using private runtime
// switches; it does not exercise the deployed platform proxy.
skipDeployment: true,
env: {
NEXT_PRIVATE_TEST_HEADERS: '1',
NEXT_PRIVATE_MINIMAL_MODE: '1',
},
})
it('returns a plain text 404 for subresource requests routed to the not-found page', async () => {
const res = await next.fetch('/web-app-manifest-192x192.png', {
headers: {
'x-matched-path': '/_not-found',
'sec-fetch-dest': 'image',
'sec-fetch-mode': 'no-cors',
'sec-fetch-site': 'same-origin',
},
})
expect(res.status).toBe(404)
expect(res.headers.get('content-type')).toContain('text/plain')
expect(res.headers.get('cache-control')).toBe(
'private, no-cache, no-store, max-age=0, must-revalidate'
)
expect(await res.text()).toBe('Not Found')
})
it('renders the not-found page for document requests', async () => {
const res = await next.fetch('/does-not-exist', {
headers: {
'x-matched-path': '/_not-found',
accept:
'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
'sec-fetch-dest': 'document',
'sec-fetch-mode': 'navigate',
},
})
expect(res.status).toBe(404)
expect(res.headers.get('content-type')).toContain('text/html')
expect(await res.text()).toContain('custom not found page')
})
it('serves the not-found RSC payload for router requests', async () => {
const res = await next.fetch('/does-not-exist', {
headers: {
'x-matched-path': '/_not-found',
rsc: '1',
},
})
expect(res.headers.get('content-type')).toContain('text/x-component')
expect(await res.text()).not.toBe('Not Found')
})
it('renders the not-found page for requests without sec-fetch-dest', async () => {
const res = await next.fetch('/whatever.bin', {
headers: {
'x-matched-path': '/_not-found',
},
})
expect(res.status).toBe(404)
expect(res.headers.get('content-type')).toContain('text/html')
expect(await res.text()).toContain('custom not found page')
})
})
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment