next.config `headers()` appends instead of overriding the default `Cache-Control` (duplicate header)

[hyf0]

Problem

A next.config headers() rule is appended after vinext's default Cache-Control rather than overriding it, producing two Cache-Control headers.

Repro

curl -sI http://localhost:3000/fonts/Source-Code-Pro-Regular.woff2 | grep -i '^cache-control'
# Cache-Control: public, max-age=3600                       <- vinext default (first)
# cache-control: public, max-age=31536000, immutable        <- next.config headers() rule

(next.config.js declares an immutable rule for /fonts/:path*.) Per HTTP header-combining rules, a shared cache may take the first max-age (3600), so the intended immutable long-cache can be ineffective.

Suggested fix

A matching headers() rule should replace vinext's default value for that header key, not append a second header.

[hyf0]

🔎 Triage — Next.js behavior vs vinext behavior

Method: grounded in the installed Next.js 15.1.12 source (node_modules/next/dist) and the exact vinext 0.1.8 dist (node_modules/vinext/dist) this issue was filed against; each conclusion independently re-checked by an adversarial second pass. vinext targets the Next.js 16 API surface, so a possible version difference was tested explicitly.

Verdict: 🐞 vinext bug (parity gap — fix needed) · should vinext fix: yes · scope: runtime-parity · confidence: high

Next.js behavior

Next.js produces a SINGLE Cache-Control header; the config headers() rule replaces the default. In resolve-routes.js the matched config header is written with its original casing and assignment semantics: resHeaders[key] = value (resolve-routes.js:477-492, key='Cache-Control'). router-server.js then applies that record via res.setHeader(key, resHeaders[key]) (router-server.js:284) — Node's setHeader is case-insensitive and REPLACES any existing same-named header. Any default Cache-Control is only set when none already exists, guarded by if (!res.getHeader('Cache-Control')) (base-server.js:1954, 2001, 2023, 2047 — getHeader is also case-insensitive). So a config Cache-Control rule for /fonts/:path* wins and there is never a duplicate header.

_{Evidence: node_modules/next/dist/server/lib/router-utils/resolve-routes.js:474-494 (route.headers loop; line 492 resHeaders[key]=value, original casing) · node_modules/next/dist/server/lib/router-server.js:282-286 and 306-307 (res.setHeader(key, resHeaders[key]) — case-insensitive replace) · node_modules/next/dist/server/base-server.js:1954 (if (!res.getHeader('Cache-Control')) guard before setting any default)}

vinext behavior

vinext emits TWO Cache-Control headers for /fonts/* because of a header-name CASING mismatch combined with a non-case-insensitive merge. (1) The static-file cache precomputes the default with the canonical capitalized key: baseHeaders['Cache-Control'] = isHashed ? immutable : 'public, max-age=3600' (static-file-cache.js:81,85); /fonts is not under /_next/static/ so it gets 'public, max-age=3600'. (2) next.config headers() rules are applied to a plain header RECORD via applyConfigHeadersToHeaderRecord, which writes the key LOWERCASED: headers[lowerName] = header.value (request-pipeline.js:106), producing middlewareHeaders['cache-control'] = 'public, max-age=31536000, immutable'. This runs at pages-request-pipeline.js:144, BEFORE the direct static serve at line 154. (3) The static file is served by serveFilesystemRoute → tryServeStatic with that record as extraHeaders (pages-request-pipeline.js:85-87 passes middlewareHeaders; prod-server.js:1087-1089). (4) tryServeStatic merges with a plain object spread: responseHeaders = { ...variant.headers, ...extraHeaders } (prod-server.js:408-411). Because 'Cache-Control' (from the cache) and 'cache-control' (from config) are DISTINCT object keys, both survive, and res.writeHead emits both — exactly matching the repro's casing (capitalized 3600 default first, lowercase immutable rule second). Note the Web-Headers path applyConfigHeadersToResponse (request-pipeline.js:88-94) uses Headers.set and would NOT duplicate; the bug is specific to the record/object path used for static-file serving.

_{Evidence: node_modules/vinext/dist/server/static-file-cache.js:80-86 (default Cache-Control with canonical 'Cache-Control' key; /fonts => 'public, max-age=3600') · node_modules/vinext/dist/server/request-pipeline.js:100-107 (applyConfigHeadersToHeaderRecord; line 106 headers[lowerName]=value lowercases the key) · node_modules/vinext/dist/server/pages-request-pipeline.js:144-154 (config headers applied to middlewareHeaders then direct static serve) and :85-87 (passes middlewareHeaders to serveFilesystemRoute) · node_modules/vinext/dist/server/prod-server.js:1087-1089 (serveFilesystemRoute -> tryServeStatic(..., stagedHeaders)) and :408-412 (responseHeaders = { ...variant.headers, ...extraHeaders }; res.writeHead emits both Cache-Control keys)}

Is it a version difference (vinext → Next 16 vs react.dev → Next 15)?

No. headers() override semantics are stable across Next 13-16: config headers are applied with res.setHeader (case-insensitive replace) producing a single header, and this is unchanged. The duplication is purely a vinext implementation artifact (lowercased record key + case-sensitive object-spread merge), not a Next 15->16 behavior change. No changelog entry alters Cache-Control header-combining for config headers().

Fix

dist/server/prod-server.js tryServeStatic (lines 408-412, and the parallel 304/no-cache and no-cache fallback merges at 396-402, 445-450): merge extraHeaders into the precomputed static headers case-insensitively (dedupe by lowercased name so the config rule REPLACES the default key). Equivalently/additionally, dist/server/request-pipeline.js:106 (applyConfigHeadersToHeaderRecord) lowercases the header key while the static cache uses canonical casing — aligning casing or doing a case-insensitive set would prevent the divergence.

---

_{🤖 Triaged with Claude Code (Opus 4.8) — read-only analysis against installed Next 15.1.12 + vinext 0.1.8 sources, adversarially verified.}