AI & Agent Dev Bug Sandbox logo
AI & Agent Dev Bug Sandbox
Back to Radar

Next.Js 16 Dev Watcher AggregateTimeout Regression Causes Dynamic Routes 404 On Large Apps

In Next.js 16, lowering watchpack's aggregateTimeout from 200ms to 5ms causes the dev server's initial page scan to fire aggregation callbacks before the scan completes. The first partial aggregation builds the dynamic route table from an incomplete page list, so dynamic pages-router routes return 404 until a later aggregation rebuilds it.

highConfidence 85%Next.jsAffected V16.0.0Affected V16.2.6Affected V16.3.0-Canary.95

Origin Analysis

The regression was introduced by PR #83628, which changed the dev watcher's watchpack aggregateTimeout from 200ms to 5ms. Watchpack's initial scan emits one change event per existing file, and with a 5ms timeout, any delay mid-scan (>5ms between file events) triggers the aggregated callback early. The first callback sees only a fraction of the routed pages and zero dynamic routes, so fsChecker.dynamicRoutes is built from that partial list.
1. Clone https://github.com/juliangruber/next-dev-partial-scan-repro 2. Run `npm install` (postinstall generates 5000 filler pages/API routes) 3. Run `npm run add-probe` to add console.error probes to node_modules/next/dist/server/lib/router-utils/setup-dev-bundler.js 4. Run `npx next dev` 5. Watch the [AGG-PROBE] logs: the first aggregated event will show routedPages count 1 and dynamicRoutes 0, then a later aggregation shows 5003 pages and 1 dynamic route. 6. During the window between the first and second aggregation, request a dynamic route like `/api/123`; it will return the 404 HTML page, while static routes work.

Fixing Code Block

Edge Case Audit

Reverting aggregateTimeout to 200 restores the previous dev server readiness delay (~195ms slower than the current 5ms value). On extremely large projects with slow filesystems where file events can be spaced more than 200ms apart, the first aggregation could still be partial, though this was rare with the pre-16 default. If the slowdown is unacceptable, roll back to 5ms and implement a more robust initial-scan completion gate instead.

Ecosystem Topology