fix(nextjs): prevent infinite handshake redirect loop on Netlify

[mauricioabreu]

Description

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

Release Notes

• Bug Fixes
  • Fixed infinite handshake redirect loop when deploying Next.js apps with Clerk development instances to Netlify
  • Improved redirect handling with fallback mechanism for Netlify deployments in development environments

[changeset-bot]

🦋 Changeset detected

Latest commit: be3ca3a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/nextjs	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Feb 18, 2026 5:50am

[wobsoriano]

This is looking good. Just a minor change! Thankss

[wobsoriano]

We can just use locationHeader here 👀

[mauricioabreu]

I don't think so? this code looks a bit different from the other frameworks

I read the other framework's implementation, and the response is built with Response(null, { status: 307, headers: requestState.headers })

In Next.js, we use NextResponse.redirect(url) and explicitly skip copying the Location header.

I mean, if we reused the locationHeader value captured before the mutation, the param added by handleNetlifyCacheInDevInstance is lost

[wobsoriano]

Copy. Looks like I have to revisit the helper. Thanks!

[wobsoriano]

thanks for correcting me here! I just checked and saw we're updating the Location header so your implementation is perfect!

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

---

📝 Walkthrough

Walkthrough

This pull request introduces a fix for an infinite handshake redirect loop that occurs when deploying Next.js applications with Clerk development instances to Netlify. The changes add Netlify cache handling in development mode by importing and invoking handleNetlifyCacheInDevInstance during redirect processing. A fallback mechanism is implemented for the Location header, using either the current Location header value or a previously captured locationHeader if the header is missing. The changes are documented in a new changeset file and do not introduce public API modifications.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: preventing an infinite handshake redirect loop on Netlify for the Next.js integration, which is directly supported by the code changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[wobsoriano]

Thank you! Let's also cherry-pick the changes here to "release/core-2" branch 🫡

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7857

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7857

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7857

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7857

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7857

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7857

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@7857

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7857

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7857

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7857

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@7857

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7857

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7857

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7857

@clerk/react

npm i https://pkg.pr.new/@clerk/react@7857

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7857

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7857

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7857

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7857

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@7857

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7857

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7857

commit: be3ca3a