In plain terms: Websites are built on frameworks that get major upgrades, like swapping a car’s engine. Some problems after the swap are loud — the car won’t start, you fix it immediately. The dangerous ones are quiet: everything looks fine, but a page that should show a project now politely says “not found.” On my own site, that quiet failure ran for months before I caught it.
The compile errors in a Next.js 14 → 15/16 migration (Next.js is the framework this site and many others are built on) fix themselves — the build tells you. The dangerous changes are the ones that keep rendering:
- Dynamic route params became Promises. In 14,
paramsis a plain object; from 15 on it’s aPromise. Code readingparams.slugwithoutawaitdoesn’t throw — it reads a property off a Promise, getsundefined, and the page quietly renders its empty or not-found state. Same forsearchParams. fetchcaching defaults flipped in 15: pages silently change between cached and per-request behavior with zero code changes.cookies()/headers()went async — sync usage survives loose type checking and only fails on the runtime paths that touch it.
The canonical fix:
- export default function Page({ params }: { params: { slug: string } }) {
- const item = getBySlug(params.slug)
+ export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
+ const { slug } = await params
+ const item = getBySlug(slug)The war story
I found this class of bug live on my own portfolio: every project detail
page had been rendering a 404 for months while returning HTTP 200. The
[slug] page read params.slug synchronously → undefined →
notFound() — but the server kept serving a prerendered shell, the listing
page worked, and nothing ever logged an error.
Fixing it unmasked a second buried bug: the page was a server component
rendering framer-motion components directly, which errors at build time —
notFound() had been bailing out before that code path ever executed, so
the build always “passed.”
What I learned
On this bug class, “it builds and the page loads” is exactly what failure
looks like. After a migration, drive every dynamic route in a real browser
and confirm actual data renders. A curl returning 200 proves nothing —
the 404 happens after hydration.
Related: Teaching AI assistants to remember past mistakes, Letting an AI hunt for the bugs humans skim past