The CI was green.
Build passed. No TypeScript errors. No warnings. Everything looked clean. I clicked deploy and went to make tea.
Came back, ope...
For further actions, you may consider blocking this person and/or reporting abuse
This is where Sentry comes in. It logs errors you missed from backend to frontend and vice-versa. It really is a neat tool to add to your tech stack. Luckily, this comes already pre-installed(kinda pre-installed) in cookiecutter-django and is easy to install it in any frontend.
Yeah, Sentry is pretty solid.
I’ve used it in a couple of projects before, mainly for catching runtime issues that don’t show up in CI or during builds. It helps once things are already in production.
In this case I was more focused on the upgrade-side stuff where nothing is actually throwing errors, so even error tracking doesn’t really catch it immediately.
You are right, it doesn't catch errors immediately. Like for example in my portfolio, the component was fetching a list. It was working perfectly fine for about 3 weeks then one day, the other day, it spat an error saying it had a fetching error.
Yeah, that kind of issue is the worst.
Working fine for weeks and then suddenly breaking makes it really hard to trust what’s actually going on, especially when nothing obvious changed.
I’ve run into similar cases where the error shows up in one place but the actual cause is somewhere else entirely. Those take way longer to track down than they should.
I agree - it takes way longer - hence the need of Sentry 😉
The pattern connecting all four is what jumps out: in each case the system expressed
certainty when it should have flagged uncertainty. Build passed. CI green. TypeScript
happy. The failure only surfaced under a real condition an actual redirect, a real
mutation, a linting issue reaching review, a specific route being hit.
That's not really an upgrade bug. It's a detection gap. The build pipeline checked
whether the code was valid, not whether the behavior was correct. Those are different
questions and Next.js 16 made that distinction expensive.
The middleware rename is the sharpest example of this. The old file was still valid
code. It compiled. TypeScript had nothing to say. The only signal the redirect wasn't
firing was the redirect not firing which you only know if you know to check it. No
tool in the standard pipeline was asking "is this file still being used at all?"
The strict mode fix for revalidateTag is the one that actually closes the detection gap
at the right layer makes it a compile error instead of a silent runtime problem. The
rest are catching it after the fact. Good reference for anyone planning the upgrade.
"Detection gap" is exactly the right framing, and exactly what it felt like in practice.
The middleware one is what stuck with me the longest. The file was valid, the export was valid, nothing complained. The only signal was the behavior being wrong, and you only catch that if you already know what it’s supposed to do. The pipeline had no way to ask whether the file still mattered.
The strict mode point is the one I’d push hardest to anyone doing this upgrade. It’s the only fix here that actually moves the check earlier. The rest are catching it after the fact.
The middleware one is exactly that, the pipeline can only check if the code is valid,
not if it still matters. those are two completely different questions and most build
tools only ask the first one. strict mode is the rare case where the fix actually moves
upstream instead of just making the downstream failure more visible.
Yeah, that distinction between “valid” and “still relevant” is exactly what made it tricky.
The middleware case really drove that home for me. Everything looked fine from the outside, but the system had basically stopped asking the only question that mattered.
Strict mode was one of the few things that actually pushed that check earlier instead of leaving it to runtime.
Strict mode doing that is probably its most underrated use. Validity passes at parse
time. Whether something is still relevant only shows up when it's actually used.
Pushing that check earlier is worth a lot when silent failures are the whole problem.
Yeah, exactly.
Most of the pipeline is just checking “is this valid?” not “does this still do anything?”. Strict mode is one of the few places where that actually shifts earlier, which ends up mattering more than it seems.
Yes, unexpected bugs often occur when updating libraries. Others who had the same problem with Next.js 16 will be helped by your post. 😀
Yeah, those upgrade bugs are the sneaky ones. Everything looks fine until a real request hits the edge case. Glad it was useful, hope it saves someone a few hours of debugging.
Yes, Next.js is very popular and used by millions of developers, so your post will surely save millions of hours for them! 🙆
This is such a valuable breakdown of the kind of upgrade issues that waste hours because nothing actually “fails” during build. The
next lintremoval and silentrevalidateTag()behavior are especially scary. Really appreciate the real-world examples and before/after fixes here. Definitely bookmarking this before my Next.js 16 migration.Really appreciate that, glad it helped. 🙌
Yeah those two were the ones that kept tripping me up the most too, especially because everything still looks “green” in CI so you don’t even get a hint something changed.
Hopefully your migration is smooth, but if anything weird shows up during it feel free to drop it here.
"Next.js 16 replaced
middleware.tswithproxy.ts" - I mean, why ... ? Seems a totally unnecessary change, only to annoy the user? On top of that, I can't imagineproxy.tsto be a "better" name thanmiddleware.ts...However - doesn't Next.js document its upgrades? As in, a CHANGELOG document or an upgrade guide?
Haha yeah fair point, proxy.ts does feel a bit odd especially when middleware.ts already made sense so the rename caught me off guard too.
From what i understood the idea is it handles more than just middleware now, closer to a full request proxy layer, but still agree the silent failure with zero warning is the jarring part.
And yeah they do have docs and a changelog, the codemod handles most of it but partial upgrades or missed files is where stuff like this sneaks through.
silent-breakage from a framework bump is the WORST class of bug - tests pass, prod misbehaves. ur 4 spots = exactly what i hit on moonshift generators (i ship next saas to user gh). added verify-phase that runs the gend app against a contract spec before deploy specifically to catch this. happy to share the contract pattern if useful, just dm.
Thanks, this is exactly the kind of thing that hurts the most, everything looks fine until prod says otherwise.
The verify phase against a contract spec sounds really interesting, that would have caught a couple of these for me.
Will DM you.
Great breakdown! That change from middleware.ts to proxy.ts is a huge one, especially for security.
A lot of apps use middleware as their only guard dog to check if a user is logged in. But if there’s a bug in the framework itself, attackers can sometimes sneak right past it.
It's always a good reminder to have a backup security check inside the actual app code, and not just at the front door. That way, if the middleware layer breaks or gets skipped during an upgrade, your data is still locked up safe.
We actually ran into this exact headache while building DevFortress, so this is a great reminder to double-check everything!
Yeah, I totally agree with the layered security point. Relying only on middleware as the single auth gate is risky, regardless of framework version. Upgrades like this just make that weakness more visible.
Defense in depth is really the key idea here. You check at the middleware level, but you also protect the actual routes and data layer underneath. That way, even if something is skipped or breaks silently, the app does not just fall open.
Sounds like a painful lesson with DevFortress, but those are usually the ones that stick. Glad the post helped as a reminder.
Thanks for sharing this. This is really useful for anyone upgrading to Next.js 16.
A safe way to fix this is to not rely only on
next build, because some upgrade issues only appear at runtime.My suggested migration checklist would be:
npx @next/codemod@canary upgrade latest
middleware.ts → proxy.ts
middleware() → proxy()
Then test any route that depends on redirects, auth, or request handling.
Old:
revalidateTag("products")
New:
revalidateTag("products", "max")
For immediate invalidation, such as webhooks:
revalidateTag("products", { expire: 0 })
next lintis removed, so package.json should use:"lint": "eslint .",
"lint:fix": "eslint . --fix"
Also update CI/CD files to run:
npm run lint
"strict": true
This helps catch silent migration issues earlier.
params
searchParams
cookies()
headers()
draftMode()
and update them to async usage where needed.
Example:
const { id } = await params
npm run lint
npm run build
npm run dev
Then manually test:
redirects
auth flow
API routes
dynamic routes
cache revalidation
dashboard/product pages
The main idea is: after a Next.js 16 upgrade, a green build is not enough. The app needs runtime testing too.
This is a really solid checklist. It covers most of the things that tripped me up too.
The runtime testing point at the end is the one I would emphasize the most. A green build only means it compiled successfully. It does not guarantee that redirects are actually firing or that revalidation is working correctly.
Strict TypeScript is underrated as well. That alone would have caught my revalidateTag issue much earlier before it ever reached staging.
Saving this for upgrade notes. Thanks for putting it together.