DEV Community: Shubhra Pokhariya

My Next.js 16 Optimistic UI Looked Perfect. Then Someone Clicked It Five Times Fast

Shubhra Pokhariya — Wed, 08 Jul 2026 07:43:35 +0000

Everything worked. I'd wired up useOptimistic on a task list, the checkbox flipped the instant you clicked it, no spinner, no half-second lag, exactly the feeling I was going for. I demoed it to myself a dozen times and moved on.

Then I did the thing you're supposed to do before you actually ship anything: I clicked it stupidly fast, five times in a row, the way an impatient real user actually would.

The checkbox stayed visually fine. The database did not. Five overlapping requests had gone out, each one flipping the same boolean, landing in whatever order the network felt like that day. Nothing crashed. Nothing logged an error. The UI just quietly stopped matching what actually happened on the server, and I had no way of knowing from looking at the screen.

That's the bug that's easy to miss with optimistic UI specifically, because the whole point of optimistic UI is that it looks right immediately. Looking right and being right are not the same claim.

The fix isn't anything specific to useOptimistic

It's the same rule as disabling a submit button while a form is in flight, just applied per row instead of per form. Track which item has a request pending, and disable it until that request settles.

const [pendingId, setPendingId] = useState<string | null>(null);

function handleToggle(id: string) {
  setPendingId(id);
  startTransition(async () => {
    setOptimisticTask(id);
    try {
      await toggleTask(id);
    } finally {
      setPendingId(null);
    }
  });
}

<input
  type="checkbox"
  checked={task.completed}
  disabled={pendingId === task.id}
  onChange={() => handleToggle(task.id)}
/>

One item at a time, scoped per row, not a global lock on the whole list. The second click on the same checkbox now does nothing instead of firing a second request that races the first one to the database, which also means one fewer redundant write your database has to process for a click that never should have gone out in the first place.

Here's what that actually looks like: five rapid clicks, one request.

The rollback question that sent me down a rabbit hole

While I was in there, I went looking for how to properly roll back an optimistic update on failure, since obviously if the toggle fails, the checkbox needs to snap back to whatever it actually was.

Almost every example I found does this:

try {
  setOptimisticTask(id);
  await toggleTask(id);
} catch {
  setOptimisticTask(id); // flip it back again to "undo"
}

It works. It's also solving a problem that, for a plain toggle like this one, doesn't need solving. useOptimistic doesn't give you a second, independent piece of state you own. It gives you a temporary value layered on top of whatever state you passed in, for exactly as long as the transition is pending. The moment that transition settles, success or failure, React drops the temporary layer and renders from the real state again. If the real state never changed, because the request failed and nothing re-fetched, the checkbox reverts on its own. No second dispatch required.

There's one real exception, and it's worth knowing before you assume the automatic revert always has your back. If the optimistic value is something the server hasn't confirmed yet at all, a new comment you added with a placeholder id before the database assigned a real one, there's no prior version of that item sitting in your base state to fall back to. A failed insert doesn't revert a flag, it has to remove something that only ever existed on the client. That's the one case where you keep your own local record of what you added and clear it yourself in the catch block. A toggle doesn't have that problem, since the value it flips already exists on the server either way.

The cache function question I didn't expect to have opinions about

Once the toggle worked, the next question was how to actually invalidate the cache after it. Next.js 16 gives you three ways to do this, and picking the wrong one either shows the user stale data or forces every page on your site to block on a single write.

revalidatePath invalidates one path. revalidateTag invalidates every cache entry sharing a tag, wherever it's used, with stale-while-revalidate behavior. updateTag, Server Actions only, expires a tag immediately so the page the user is currently on reflects their own write right away.

For a checkbox someone is staring at as they click it, updateTag is the right one. If that same task count also fed a sidebar stat somewhere else on the site, one that nobody's watching in real time, revalidateTag on that same tag lets it catch up a beat later instead of forcing every page on the site to block on one write.

One thing worth knowing if you're on a recent Next.js 16 version: revalidateTag now requires a second argument.

revalidateTag("tasks", "max"); // recommended in Next.js 16+

revalidateTag("tasks") alone is deprecated and will throw a TypeScript error.

The error boundary detail that only matters if your error comes from data fetching

Last piece: what happens when the request just fails outright, not a validation error, an actual dropped connection. Next.js docs are clear that an error thrown inside startTransition still bubbles up to the nearest error.tsx, transition or not.

What I didn't know until I went looking: as of Next.js 16.2, error.tsx ships a second recovery prop, unstable_retry, sitting alongside the older reset. They're not interchangeable. reset wipes the error and lets the same children render again exactly as they were, no new fetch involved, so if the underlying data never loaded in the first place, you're just showing the same broken screen a second time. unstable_retry actually goes back to the server and re-renders the segment fresh, which is the one that fixes anything when the failure came from a fetch.

export default function TaskListError({
  error,
  unstable_retry,
}: {
  error: Error & { digest?: string };
  unstable_retry: () => void;
}) {
  return (
    <div role="alert">
      <p>Something went wrong loading your tasks.</p>
      <button onClick={() => unstable_retry()}>Try again</button>
    </div>
  );
}

reset still has a place, specifically when you want to clear an error and re-render without touching the network at all. For a segment whose entire job is showing fetched data, that's rarely the case.

Where the rest of this lives

I wrote the full version of this with the complete before/after code, the decision table for all three revalidation functions, and the Suspense boundary pattern for streaming a mutation's result without blocking the rest of the page, over on my site: "I Added Optimistic Updates to a Next.js 16 App. Here's Every Rollback Bug I Hit." It follows directly from the Server Actions bugs I wrote up in an earlier post, if you want the context on useActionState and why redirect can't sit inside a try/catch.

Has anyone else had an optimistic UI look perfect in every demo and then fall apart the moment a real user clicked faster than you did? I'd genuinely like to know if the rapid-click case is as common as it felt once I actually looked for it.

Note: AI used for image editing.

My Next.js 16 Auth Passed Every Test. Five Bugs That Only Showed Up When I Wired It Together.

Shubhra Pokhariya — Tue, 30 Jun 2026 06:01:36 +0000

The three-layer model works. Part 1 of this series is the invoice incident that proved it. Part 2 is the proxy.ts matcher gaps that fail silently. Part 3 is the mutation-layer auth check that gets skipped even when everything else looks solid. My kit implements this in Route Handlers rather than Server Actions, but the principle is identical: every mutation endpoint verifies the caller before touching data.

I built all three layers correctly. Then I tried to ship a complete auth kit on top of them.

Email and password login. Google and GitHub OAuth. Email verification. Password reset. Role-based routes. An admin panel with live database stats. A UI a real person would trust with a real password.

That is when the integration bugs appeared. Not architecture bugs. Wiring bugs. The kind that only exist once every piece is connected and real flows run through the whole thing.

Five of them. Here is exactly what happened.

Bug 1: The Cookie Write That Reported Success and Then Vanished

Login returned 200. Tokens in the response. Client wrote the cookie. The very next request redirected straight back to login.

I went to the JWT first. The JWT was fine. The proxy was fine. The cookie was simply not there on the next request.

Here is what was actually happening. After a successful login call, the client was writing the cookie with document.cookie = .... In certain browser and timing combinations on localhost, that write reported success. document.cookie.includes('auth_tokens') returned true immediately after the assignment. Then a few seconds later, gone. No error. No warning.

The fix was not about the timing. It was moving the write to where it belonged from the start.

// app/api/auth/login/route.ts
const COOKIE_NAME = process.env.NEXT_PUBLIC_AUTH_COOKIE_NAME ?? "auth_tokens";

// ... after building responseBody and cookieTokens ...

const response = NextResponse.json(responseBody, { status: 200 });

const isSecure =
  request.headers.get("x-forwarded-proto") === "https" ||
  request.nextUrl.protocol === "https:";

const maxAge = rememberMe === true ? 60 * 60 * 24 * 30 : 60 * 60 * 24 * 7;

response.cookies.set(COOKIE_NAME, JSON.stringify(cookieTokens), {
  httpOnly: true,
  sameSite: "lax",
  secure: isSecure,
  path: "/",
  maxAge,
});

return response;

httpOnly: true means no JavaScript on the page can read this cookie at all. A script injected through an XSS vulnerability still cannot steal the session token because the token is invisible to every script. The browser stores it automatically from the Set-Cookie response header. Nothing to silently vanish.

As Part 1 covered, the proxy reads the session from a cookie, not localStorage. httpOnly closes both issues at once: the proxy can see the cookie, and client-side scripts cannot touch it.

If the client is writing something the server should write, stop debugging the client write. Move it.

Bug 2: The Navigation That Never Reached the Proxy

Cookie fixed, server-set, httpOnly. Still redirecting back to login.

After the login API returned 200, the form called window.location.href. But before I landed on that fix I had tried router.push(redirectTo) first. That is where the second bug was hiding.

router.push is a client-side navigation. No real HTTP request fires. The browser has no reason to attach the newly set cookie to anything outgoing because nothing crossed the network. proxy.ts only sees real HTTP requests. A route change that stays inside React's router is invisible to it. This is the same boundary Part 2 covered when explaining why matcher gaps are invisible at the proxy level: the proxy cannot check what it never sees.

The login form uses window.location.href for exactly this reason:

// app/login/login-form.tsx
async function handleSubmit(e: FormEvent<HTMLFormElement>): Promise<void> {
  e.preventDefault();
  setError(null);
  setIsSubmitting(true);

  try {
    await login(email.trim(), password, rememberMe);
    window.location.href = redirectTo; // real HTTP GET, proxy sees the cookie
  } catch (err) {
    // ... error handling
    setIsSubmitting(false);
  }
}

window.location.href forces a full page reload. A genuine HTTP GET. The browser attaches every cookie it holds. The proxy sees it because this request actually crossed the network.

Bug 3: A Database Integer in the JWT Sub Claim

Cookie arriving correctly. Proxy still rejecting the token.

Debug logging showed the JWT decoding fine. Every claim present. The type guard in extractPayload kept failing on sub. typeof sub !== 'string' kept returning true even though the value looked like a user ID.

The database id column is SERIAL, a Postgres integer. When that integer got passed into jose's .setSubject() without an explicit cast, it was serialized into the token as a number. The extractPayload function checks typeof sub !== "string" and throws if that fails. It was doing exactly what it should. The claim was wrong because of an upstream assumption that never held for an integer primary key.

The fix is in lib/auth/jwt.ts on both signAccessToken and signRefreshToken:

// lib/auth/jwt.ts
export async function signAccessToken(
  payload: SignablePayload,
): Promise<string> {
  return (
    new SignJWT({
      role: payload.role,
      email: payload.email,
      permissions: payload.permissions,
    })
      .setProtectedHeader({ alg: "HS256" })
      // Always cast to string here. Postgres ids that come through as
      // numbers will otherwise get signed as numbers, and proxy.ts expects
      // sub to always be a string when it verifies the token.
      .setSubject(String(payload.sub))
      .setIssuedAt()
      .setExpirationTime(ACCESS_TOKEN_TTL)
      .sign(ACCESS_SECRET)
  );
}

String(payload.sub) on both signAccessToken and signRefreshToken. One word. The extractPayload type guard that catches this is correct. The claim was malformed, just not visibly, because a number and a number-as-string look identical in a console log.

This bug is invisible in development if test data uses string IDs. It only surfaces when a real SERIAL column meets a JWT library that validates claim types strictly.

Bug 4: OAuth Sign-In When the Same Email Already Has a Password Account

Email and password auth working end to end. Time to add Google and GitHub.

The OAuth flow itself is documented well enough. The question that actually needed answering: what happens when someone who already has a password account later clicks "Continue with Google" using the same email address?

The callback route handles three distinct cases:

// app/api/auth/google/callback/route.ts

// Case 1: they've signed in with Google before, google_id already set
let user = await db.queryOne<UserRow>(
  `SELECT id, email, name, role, is_active, google_id
   FROM authkit_test_users
   WHERE google_id = $1`,
  [googleUser.sub],
);

if (!user) {
  // Case 2: no google_id match, but email matches an existing row
  const existingByEmail = await db.queryOne<UserRow>(
    `SELECT id, email, name, role, is_active, google_id
     FROM authkit_test_users
     WHERE email = $1`,
    [normalizedEmail],
  );

  if (existingByEmail) {
    // Linking is safe here because Google has already verified this
    // email belongs to whoever is sitting at the browser right now.
    // email_verified gets set true at the same time, in case they
    // registered with a password earlier and never finished clicking
    // their own verification link.
    await db.query(
      `UPDATE authkit_test_users
       SET google_id = $1, email_verified = true
       WHERE id = $2`,
      [googleUser.sub, existingByEmail.id],
    );
    user = existingByEmail;
  } else {
    // Case 3: brand new person, create the row
    // password_hash stays null, role always defaults to 'user'
    const rows = await db.query<UserRow>(
      `INSERT INTO authkit_test_users
         (email, password_hash, name, role, is_active, email_verified, google_id)
       VALUES ($1, NULL, $2, 'user', true, true, $3)
       RETURNING id, email, name, role, is_active, google_id`,
      [normalizedEmail, googleUser.name ?? null, googleUser.sub],
    );
    user = rows[0] ?? null;
  }
}

The linking in Case 2 is safe specifically because of who verified the email. Google has already confirmed this email belongs to whoever is sitting at the browser. That is a stronger guarantee than most apps' own verification flow. The unsafe version of this pattern is linking accounts based on an email someone simply typed into a field with no third-party verification behind it.

Role always defaults to 'user' on new accounts. There is no code path a visitor can trigger that grants admin through a sign-in button.

GitHub needed one extra step Google does not. Google always returns a verified email with the basic profile request. GitHub does not. Many users set their email to private, so the profile response comes back with email: null. The fix is a second request to GitHub's emails endpoint, filtering for the address marked both primary and verified. No verified primary email means the account cannot sign in this way.

Both providers on the same sign-in screen. The three-case account lookup in Bug 4 is what makes this safe when the same email already exists from a password registration.

Bug 5: Forgot Password for an Account That Never Had a Password

This one does not show up until you have built both OAuth and email/password auth and put them in the same product.

A user registers with Google. Months later they land on the forgot password page and type in their email, because they have genuinely forgotten they always came in through the Google button and never set a password.

Without handling this, that person gets a password reset email for a password that has never existed. The link technically works. The experience makes no sense and they leave more confused than before.

The password_hash column stays null for every OAuth-only account. That is the check:

// app/api/auth/forgot-password/route.ts

if (!user.password_hash) {
  // This account signed in through an OAuth provider and never set a
  // password. Send a message pointing at whichever one they actually
  // used rather than sending a reset link for a password that doesn't exist.
  const provider = user.google_id
    ? "Google"
    : user.github_id
      ? "GitHub"
      : "Google or GitHub";

  try {
    await resend.emails.send({
      from: process.env.RESEND_FROM_EMAIL ?? "noreply@example.com",
      to: normalizedEmail,
      subject: `Sign in with ${provider}`,
      html: buildOAuthOnlyEmail({ name: user.name, provider }),
    });
  } catch {
    // Email failed to send, the generic response goes out either way
  }
  return NextResponse.json(genericSuccessBody, { status: 200 });
}

The buildOAuthOnlyEmail function is in the same file. It generates a plain HTML email that tells the person their account was created with that provider and links them back to the sign-in page. No password reset link. No confusion.

The browser response is identical regardless of which branch runs:

const genericSuccessBody = {
  message:
    "If an account exists for this email, we've sent you instructions.",
};

Same message, same 200 status, whether the user has a password, uses OAuth, or does not exist at all. This endpoint should never confirm or deny which email addresses are in your system.

Same page, same response to the browser, for every email submitted. The branching on password_hash happens entirely on the server side.

What Shipped After These Five Bugs Were Gone

Registration with bcrypt hashing, a live password strength meter, and a terms checkbox. Email verification and password reset through Resend with separate token lifetimes: 24 hours for verification, 1 hour for reset. Google and GitHub OAuth with the account linking logic above. Role-based routes. An admin panel pulling live counts from the database. A 403 page instead of a crash when someone hits a route their role does not cover.

The data layer ownership pattern from Part 1 runs on every query. WHERE user_id = $1 inside the SQL, not as a wrapper around the result. The auth check pattern from Part 3 runs on every mutation endpoint. Verify the caller before touching data. Both are in the kit exactly as written in the earlier posts in this series.

Live database counts in the admin panel. Anyone without the admin role who hits this URL directly lands on the 403 page instead.

One Tailwind v4 issue worth naming because it produces zero errors. Next.js 16 on Turbopack has a documented file watching problem where Tailwind's class detection misses .tsx files entirely. Clean build, no warnings, completely unstyled HTML. The fix:

/* app/globals.css — add after @import "tailwindcss" */
@source "../app/**/*.{ts,tsx}";
@source "../components/**/*.{ts,tsx}";
@source "../lib/**/*.{ts,tsx}";

Three lines and everything renders correctly.

Three Things for the Auth Checklist After This Build

Parts 1 through 3 of this series built a checklist of things that work locally and break in production. Three more belong on it now.

Client-side cookie writes can silently vanish with no error. Move the write to the server with response.cookies.set(). That is where it belongs regardless of any timing issue.

router.push after login does not trigger the proxy. If the proxy needs to read a freshly set cookie on the next request, that request has to be a real HTTP GET. Use window.location.href.

Wrap integer primary keys in String() before signing a JWT. .setSubject(String(payload.sub)) not .setSubject(payload.sub). A SERIAL column is an integer. The JWT type guard that catches this is correct. The claim is malformed, just not visibly so.

Get the Auth Kit

Everything in this series built into one kit: three-layer security, email and password, Google and GitHub OAuth, email verification, password reset, role-based access, admin panel, and deployment guide. Next.js 16 Auth Kit at shubhra.dev

The full implementation tutorial with every code file, database schema, and deployment notes is at I Built a Next.js 16 Auth Kit. Every Edge Case I Found Is in Here.

Has anyone else hit the OAuth forgot-password edge case before it shipped? I started paying attention to it after this build. More common than I expected. People who register with Google genuinely try the forgot password page later because they forget how they originally signed in. Curious whether others caught it early or found out from a user.

Note: AI used for image editing.

Next.js 16 Server Actions Security: The Auth Check Most Developers Miss

Shubhra Pokhariya — Wed, 24 Jun 2026 17:24:06 +0000

I keep seeing it on code reviews. Proxy solid. Auth on every Server Component. Header direction correct.

Then I look at the Server Actions.

No auth check. Not one. The page that renders the button is protected. The action behind the button accepts whatever the caller sends -- any valid session, any resource ID, no ownership verification anywhere.

'use server' doesn't add authentication. It exposes an HTTP endpoint. Anyone with a valid session cookie and a cURL command can call it directly, no UI required.

That's what this post covers.

What "use server" does, and what it does not do

When you add 'use server' to a file or a function, you're telling Next.js to move that code to the server and expose it as a callable endpoint. That's all it does.

It does not add authentication. It does not check who is calling. It does not verify that the caller has any session at all. From the official Next.js 16 docs:

Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation.

Public-facing API endpoints. That's exactly what they are. Anyone who can construct a POST request to the right URL can call your Server Action. No browser required. No UI required. A cURL command with a valid session cookie is enough.

The shift that matters: when you write a Server Action, you're not writing an internal helper that only runs when a user clicks a specific button. You're writing a public HTTP endpoint that also happens to be invokable from a button. Completely different from a security standpoint.

Next.js does give you two protections out of the box worth knowing about. Action IDs are encrypted and non-deterministic, recalculated between builds, so old IDs stop working after a deploy. Unused Server Actions are removed from the client bundle entirely through dead code elimination. Both things help reduce your attack surface. Neither one is authentication.

The gap that looks fine until it isn't

This is the pattern I keep finding on code reviews:

// app/dashboard/posts/[id]/page.tsx
import { verifySession } from '@/app/lib/dal'
import { deletePostAction } from './actions'

export default async function PostPage({ params }) {
  const session = await verifySession()  // Page is protected

  return (
    <div>
      <h1>Edit Post</h1>
      <form action={deletePostAction}>
        <input type="hidden" name="postId" value={params.id} />
        <button type="submit">Delete</button>
      </form>
    </div>
  )
}

// app/dashboard/posts/[id]/actions.ts
'use server'

import { db } from '@/lib/db'

export async function deletePostAction(formData: FormData) {
  const postId = formData.get('postId') as string

  // No auth check. The page already verified the user.
  await db.post.delete({ where: { id: postId } })
}

The page check runs at render time and confirms the user is authenticated before the UI appears. The action check never runs because nobody added one. The action will accept a delete request from anyone with any valid session, for any post ID, with no verification that the caller owns the post.

The fix is treating the action as its own entry point with its own verification:

// app/dashboard/posts/[id]/actions.ts
'use server'

import { verifySession } from '@/app/lib/dal'
import { db } from '@/lib/db'

export async function deletePostAction(formData: FormData) {
  const session = await verifySession()
  const postId = formData.get('postId') as string

  const post = await db.post.findUnique({ where: { id: postId } })

  if (!post || post.authorId !== session.userId) {
    throw new Error('Not found')
  }

  await db.post.delete({ where: { id: postId } })
}

Two changes. verifySession() runs first, independent of whether the page ran it. The ownership check runs before the delete.

Same error for "not found" and "not authorized" is intentional. Different error messages let a caller figure out which post IDs exist in your system. One generic error closes that.

The Data Access Layer: why it exists

Once you start adding auth checks, ownership checks, and business logic inside every action, the actions get long and hard to audit. I used to copy-paste the ownership check into every action that touched posts. Then I changed the logic in one place and forgot the other four. A user found the gap before I did. The Data Access Layer pattern fixed that permanently.

Centralize all auth logic and database access in a separate module marked with server-only. Keep your actions thin. Actions receive input, call DAL functions, handle Next.js-specific things like cache revalidation. That's it.

// app/lib/dal.ts
import 'server-only'
import { cookies } from 'next/headers'
import { decrypt } from '@/app/lib/session'
import { cache } from 'react'
import { redirect } from 'next/navigation'

export const verifySession = cache(async () => {
  const cookie = (await cookies()).get('session')?.value
  const session = await decrypt(cookie)

  if (!session?.userId) {
    redirect('/login')
  }

  return { isAuth: true, userId: session.userId as string }
})

server-only at the top is not decoration. It causes a build error if this module ever gets imported from a Client Component. The auth logic physically cannot reach the browser because the build won't allow it. That's stronger than any code review convention.

The cache() wrapper from React is worth understanding too. When verifySession() gets called multiple times during the same render pass, once from the page, once from a leaf component, once from a data function, React deduplicates those calls automatically. One cookie read, one JWT verification, one result shared across the render. No repeated work.

Now the DAL functions:

// app/lib/dal.ts (continued)
import { db } from '@/lib/db'

export const getUserPost = cache(async (postId: string) => {
  const session = await verifySession()

  const post = await db.post.findUnique({
    where: { id: postId },
    select: { id: true, title: true, content: true, authorId: true }
  })

  if (!post || post.authorId !== session.userId) {
    return null
  }

  return post
})

export const deleteUserPost = async (postId: string) => {
  const session = await verifySession()

  const post = await db.post.findUnique({ where: { id: postId } })

  if (!post || post.authorId !== session.userId) {
    throw new Error('Not found')
  }

  await db.post.delete({ where: { id: postId } })
}

And the action becomes thin:

// app/dashboard/posts/[id]/actions.ts
'use server'

import { deleteUserPost } from '@/app/lib/dal'
import { revalidatePath } from 'next/cache'

export async function deletePostAction(formData: FormData) {
  const postId = formData.get('postId') as string
  await deleteUserPost(postId)
  revalidatePath('/dashboard/posts')
}

The action does two things: call the DAL function and handle cache invalidation. Everything else lives in the DAL where it's reviewable and testable in one place.

The Layout trap that catches everyone once

A lot of developers put their auth check in a shared Layout component because it feels efficient. One check, covers everything under that route segment. The official docs have a specific warning about this:

Due to Partial Rendering, be cautious when doing checks in Layouts as these don't re-render on navigation, meaning the user session won't be checked on every route change.

What that means in practice: a user navigates to /dashboard, the Layout checks their session. They then navigate to /dashboard/billing. The Layout does not re-render. No session check runs for that navigation. If that user's session was revoked between those two navigations, the billing page renders anyway.

The fix is straightforward. Layouts fetch user data for display purposes, name in the nav, avatar, that kind of thing. The authorization check belongs in the page component or the DAL function it calls, not in the Layout.

// app/dashboard/layout.tsx
import { getUser } from '@/app/lib/dal'

export default async function DashboardLayout({ children }) {
  const user = await getUser()  // For display only, not auth enforcement

  return (
    <div>
      <nav>Welcome, {user.name}</nav>
      {children}
    </div>
  )
}

// app/dashboard/billing/page.tsx
import { verifySession } from '@/app/lib/dal'
import { getUserPermissions } from '@/app/lib/dal'
import { redirect } from 'next/navigation'

export default async function BillingPage() {
  const session = await verifySession()  // Runs on every navigation to this page
  const permissions = await getUserPermissions(session.userId)

  if (!permissions.includes('billing:read')) {
    redirect('/unauthorized')
  }

  // render billing content
}

Because verifySession() lives in the DAL and gets called from the page component directly, it runs on every navigation to that page regardless of what the Layout did or did not do.

Roles vs permissions inside actions

Roles are coarse and stable. They live in the session payload. Checking a role inside a DAL function costs nothing extra because the session is already decrypted:

// app/lib/dal.ts
export const verifyAdminSession = cache(async () => {
  const session = await verifySession()

  if (session.role !== 'admin') {
    redirect('/unauthorized')
  }

  return session
})

Permissions are granular and they change independently of session rotation. If you revoke a user's billing:export permission at 2pm, you want that to take effect immediately, not when their session next expires. That means a database call:

// app/lib/dal.ts
export const getUserPermissions = cache(async () => {
  const session = await verifySession()

  const permissions = await db.permission.findMany({
    where: { userId: session.userId },
    select: { name: true }
  })

  return permissions.map(p => p.name)
})

Because getUserPermissions is wrapped in cache(), if it gets called from both the page component and a leaf component during the same render, the database query runs once. Covered in Part 2 briefly, but the DAL pattern is where this actually becomes useful because the cache wrapper lives in one place and applies everywhere the function is called.

What to return from Server Actions

Server Action return values get serialized and sent to the client. If you return a raw database record, the client gets every column including ones it should never see. This happens by accident more than people realize:

// This sends passwordHash, stripeCustomerId, internalNotes to the browser
'use server'
export async function updateProfile(formData: FormData) {
  const session = await verifySession()

  return db.user.update({
    where: { id: session.userId },
    data: { name: formData.get('name') as string }
  })
}

// Return only what the UI needs
'use server'
export async function updateProfile(formData: FormData) {
  const session = await verifySession()

  await db.user.update({
    where: { id: session.userId },
    data: { name: formData.get('name') as string }
  })

  return { success: true, name: formData.get('name') }
}

When your DAL functions use explicit select statements, this is mostly handled automatically. The action returns what the DAL gives it. The DAL selects only the columns it needs. Nothing extra reaches the client.

Before you ship

Every Server Action calls verifySession() before touching data
Every mutation checks ownership before executing, not after
DAL functions use server-only and explicit select statements
Auth checks live in page components, not Layouts
Return values are DTOs, not raw database records
Test every action directly with cURL or a REST client before deploying, not just through the UI

That last one is the test. If hitting an action endpoint directly with a valid session cookie returns data or executes a mutation it should not, the UI protecting it does not matter.

Where this series ends

Part 1 was the invoice incident. One missing ownership check in a data function. Technically correct auth at every layer that actually existed, and one layer that did not exist.

Part 2 was the proxy.ts gate. The matcher failures that happen silently, the header direction bug, and getVerifiedUser() to close the header trust boundary.

This post is the layer that catches mutations. verifySession() in every Server Action independent of the page that rendered the button. Ownership checks before every mutation. The DAL pattern so the auth logic lives in one place. DTOs so the client only gets what it needs.

Three independent checks. One bug doesn't open the door.

I still see the missing action check on almost every code review I do. Not in the proxy. Not in the page. In the action, quietly accepting whatever the caller sent.

Full implementation with all three layers at Next.js 16 Authentication: The 3-Layer Security Model That Catches What proxy.ts Misses. Loading states, error handling, useActionState, and cache invalidation patterns in Server Actions are covered in Next.js 16 Server Actions: The Bugs That Only Show Up in Production.

Note: I use AI for editing and image generation, but the technical substance is from my own work.

I Got the proxy.ts Matcher Wrong for Three Projects Before I Understood Why

Shubhra Pokhariya — Wed, 17 Jun 2026 07:56:06 +0000

A few days ago I published a post about the three-layer auth model and the invoice incident that made me rebuild how I think about Next.js 16 auth. More people had hit the same thing than I expected.

One comment stopped me. Someone pointed out a real gap in how the forwarded headers work when the matcher misses a route. They were right, and I want to cover it properly here. But before that, I want to go through proxy.ts end to end, because in my experience the matcher is where most auth setups quietly break first, and it breaks in the worst way, no error, no warning, nothing in the logs.

Why the Name Changed

If you've been building with Next.js for a while, the rename felt arbitrary at first. middleware.ts to proxy.ts. Same location in your project, different filename, different export.

The Next.js team has been direct about why. The word "middleware" created real confusion. Developers coming from Express thought of it as a pipeline, stack things up, run them in order, app.use everything. That's not what this is and it led to people using it for things it was never meant to do: database calls, heavy business logic, session management.

What it actually does is sit at the network boundary in front of your app and intercept requests before they reach your routes. That's a proxy. The rename is the team saying: this has a specific job. Stop treating it like a general-purpose request pipeline.

The official docs are pretty clear:

Proxy is meant to be invoked separately of your render code. You should not attempt relying on shared modules or globals.

No database calls. No heavy logic. That belongs in the layers behind it, which is exactly what the previous post was about.

The Runtime Change That Actually Matters for Auth

middleware.ts defaulted to the Edge runtime. The Edge runtime had limited crypto support. Verifying JWTs with certain algorithms meant lighter libraries, specific workarounds, and sometimes things that just didn't work depending on which signing algorithm your tokens used.

proxy.ts runs on the Node.js runtime by default in Next.js 16. Full crypto support. jose works completely. Any standard JWT library works. No workarounds.

From the official version history:

v16.0.0: Middleware is deprecated and renamed to Proxy. Proxy defaults to the Node.js runtime

The Node.js runtime in proxy.ts is not configurable. The docs are explicit: the edge runtime is not supported in proxy, the runtime is nodejs, and it cannot be configured. Don't try to change it.

Edge runtime is still available through middleware.ts, which still exists in Next.js 16 for edge-specific cases like geographic redirects or A/B testing at the CDN level. But middleware.ts is deprecated. For auth, you want proxy.ts.

Migrating From middleware.ts

If you haven't done this yet, two options.

Full upgrade codemod for all Next.js 16 breaking changes:

npx @next/codemod@canary upgrade latest

Only the middleware migration if that's all you need:

npx @next/codemod@canary middleware-to-proxy .

After running either one, check these three things manually. Don't trust the codemod alone:

proxy.ts exists at your project root, same level as the app folder
The exported function is named proxy, not middleware
middleware.ts is gone

That third one is more important than it sounds. If you manually bumped the package version without the codemod, your old middleware.ts sits there, compiles clean, passes TypeScript checks, and does nothing at runtime. Routes that should be intercepted aren't. Redirects don't fire. No error anywhere. The file is just silently bypassed.

I covered this in the 4 places Next.js 16 broke my app post. This is the one that hurt the most because everything looks fine until a real redirect fails to fire in staging.

Also check next.config.js if you had skipMiddlewareUrlNormalize — configuration flags containing the middleware name are renamed in Next.js 16, so this is now skipProxyUrlNormalize. The codemod handles it, but worth verifying manually.

Building the proxy.ts Auth Gate

Three decisions in this code that look obvious but aren't. I'll walk through each one after.

// proxy.ts
import { NextResponse } from "next/server"
import type { NextRequest } from "next/server"
import { jwtVerify } from "jose"

// npm install jose
const JWT_SECRET = new TextEncoder().encode(process.env.JWT_SECRET!)

const PUBLIC_ROUTES = [
  "/login",
  "/register",
  "/forgot-password",
  "/reset-password",
  "/api/auth/login",
  "/api/auth/refresh",
  "/api/auth/logout",
  "/",
  "/about",
  "/pricing",
  "/blog",
]

const ROLE_ROUTES: Record<string, string[]> = {
  "/admin": ["admin"],
  "/dashboard": ["admin", "user", "moderator"],
  "/moderator": ["admin", "moderator"],
  "/api/admin": ["admin"],
  "/api/user": ["admin", "user", "moderator"],
}

export async function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl

  if (PUBLIC_ROUTES.some((route) => pathname.startsWith(route))) {
    return NextResponse.next()
  }

  const tokenCookie = request.cookies.get("auth_tokens")?.value

  if (!tokenCookie) {
    const loginUrl = new URL("/login", request.url)
    loginUrl.searchParams.set("redirect", pathname)
    return NextResponse.redirect(loginUrl)
  }

  try {
    const tokens = JSON.parse(tokenCookie)
    const { payload } = await jwtVerify(tokens.accessToken, JWT_SECRET)
    const role = payload.role as string

    for (const [route, allowedRoles] of Object.entries(ROLE_ROUTES)) {
      if (
        (pathname === route || pathname.startsWith(route + "/")) &&
        !allowedRoles.includes(role)
      ) {
        return NextResponse.redirect(new URL("/unauthorized", request.url))
      }
    }

    // Headers go on the request, not the response
    // Server Components read incoming request headers via headers()
    // Setting them on the response sends them to the browser instead
    const requestHeaders = new Headers(request.headers)
    requestHeaders.set("x-user-id", payload.sub as string)
    requestHeaders.set("x-user-role", role)
    requestHeaders.set("x-user-email", (payload.email as string) ?? "")

    return NextResponse.next({
      request: { headers: requestHeaders },
    })
  } catch {
    // Expired token, malformed JWT, bad JSON — all redirect to login
    // Same response for all three, no information leak about which failed
    const loginUrl = new URL("/login", request.url)
    loginUrl.searchParams.set("redirect", pathname)
    return NextResponse.redirect(loginUrl)
  }
}

export const config = {
  matcher: [
    "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt|.*\\.png$|.*\\.jpg$|.*\\.webp$|.*\\.svg$|.*\\.ico$).*)",
  ],
}

Decision 1: The Matcher

This is where most auth setups break. And the way it breaks is the worst possible kind.

Without a matcher, the proxy runs on every request. Every CSS file. Every JS bundle. Every image. That's a JWT verification attempt on each one. When an unauthenticated user hits a CSS request, they get redirected to login, which has no token, which redirects to login again. Infinite redirect loop on static assets. Your app loads for authenticated users but something always feels slow and wrong, and the logs don't explain it.

The negative lookahead in the matcher above excludes static files and keeps the proxy on actual routes:

_next/static : compiled JS and CSS bundles
_next/image : image optimization endpoint
favicon.ico, sitemap.xml, robots.txt : metadata files
.*\\.png$ and the other image extensions : public folder assets

One behavior worth knowing: even if you exclude _next/data in your matcher, the proxy still runs for _next/data routes. This is intentional by design. If you protect a page, the proxy deliberately still covers the corresponding data route so you can't accidentally leave it exposed.

Matcher values must be constants. Statically analyzed at build time. Dynamic values, variables, anything computed gets silently ignored. Another way auth gaps get introduced with zero error output.

Decision 2: The Header Direction

I got this backwards the first time I wrote it.

// This is correct. Headers reach your Server Components
return NextResponse.next({
  request: { headers: requestHeaders },
})

// This is wrong. Headers go to the browser instead
// No error produced
return NextResponse.next({
  headers: requestHeaders,
})

headers() in a Server Component returns incoming request headers. If you set the x-user-id header on the response instead of on the forwarded request, every headers().get("x-user-id") call in your pages returns null. Every authenticated user gets redirected to login. Nothing in the logs to explain it. Took me way longer to debug than it should have.

Decision 3: The try/catch

The catch block handles three failure modes with one redirect: the cookie is valid JSON but the tokens object is malformed, the JWT is structurally broken, or the JWT is expired. All three end at login with no indication of which failed.

Different error responses for different failure modes tell an attacker something about the state of your system. One generic redirect tells them nothing.

The Header Trust Boundary

The proxy sets x-user-id on the request headers before forwarding. Server Components read it with headers().get("x-user-id"). Works fine when the proxy runs.

When does the proxy not run? When the matcher has a gap.

Add a new route, forget to check it falls inside the matcher pattern, the proxy never runs for that route. Nobody set x-user-id. Now a client sends their own x-user-id: someone_elses_id header on that unmatched route. The Server Component reads it. From inside the Server Component, a proxy-set header and a client-sent header look identical — there's no way to tell the difference.

What breaks: if you use that userId to query data, the data layer's AND user_id = $2 still scopes the query correctly. Actual records don't leak. But getUserPermissions(userId) now runs against the wrong user entirely. The attacker gets a different user's permissions back. No records exposed, but a real authorization failure on a specific route.

The fix is verifying the JWT directly from the cookie in the Server Component instead of trusting the forwarded header.

// lib/auth-server.ts
import { cookies } from "next/headers"
import { jwtVerify } from "jose"

const JWT_SECRET = new TextEncoder().encode(process.env.JWT_SECRET!)

type AuthUser = {
  userId: string
  role: string
  email: string
}

export async function getVerifiedUser(): Promise<AuthUser | null> {
  const cookieStore = await cookies()
  const tokenCookie = cookieStore.get("auth_tokens")?.value

  if (!tokenCookie) return null

  try {
    const tokens = JSON.parse(tokenCookie)
    const { payload } = await jwtVerify(tokens.accessToken, JWT_SECRET)

    return {
      userId: payload.sub as string,
      role: payload.role as string,
      email: (payload.email as string) ?? "",
    }
  } catch {
    return null
  }
}

Using it in a Server Component:

// app/dashboard/billing/page.tsx
import { redirect } from "next/navigation"
import { getVerifiedUser } from "@/lib/auth-server"
import { getUserPermissions, getUserInvoices } from "@/lib/data"

export default async function BillingPage() {
  const user = await getVerifiedUser()

  if (!user) {
    redirect("/login")
  }

  const permissions = await getUserPermissions(user.userId)

  if (!permissions.includes("billing:read")) {
    redirect("/unauthorized")
  }

  const invoices = await getUserInvoices(user.userId)
  return <BillingView invoices={invoices} />
}

Yes, this verifies the JWT twice on requests that go through the proxy. The proxy verifies at the network boundary, the Server Component verifies again at render time. That feels redundant. It isn't.

The proxy verification is the fast gate. The Server Component verification removes the trust dependency on the proxy having run at all. On a route where the proxy ran normally, the second verification takes a few milliseconds. On a route where the matcher had a gap, it's what closes the hole. Trusting a header any client can send on any unmatched route is not worth the few milliseconds saved.

Server Functions and the Proxy

Something in the official docs tucked into the execution order section that gets missed:

Server Functions are not separate routes in this chain. They are handled as POST requests to the route where they are used, so a Proxy matcher that excludes a path will also skip Server Function calls on that path.

If your matcher excludes a path, Server Actions on that path run without proxy coverage too. The docs explicitly say to verify authentication and authorization inside each Server Function, not rely on proxy coverage alone.

Same principle as the three-layer model. The proxy is the fast gate, not the complete answer.

Where proxy.ts Sits in the Request Flow

From the official docs, the actual execution order:

headers from next.config.js
redirects from next.config.js
proxy.ts
beforeFiles rewrites from next.config.js
Filesystem routes (public/, _next/static/, pages/, app/)
afterFiles rewrites from next.config.js
Dynamic routes
fallback rewrites from next.config.js

Third. After next.config.js headers and redirects, before anything in the filesystem renders. That's why it's cheap, it intercepts before any React component work starts.

Three Things to Check Before You Ship

JWT_SECRET in every environment. Always in .env.local. Easy to forget in staging or production. The jwtVerify call throws an opaque error when it's missing and authenticated users get sent to login with nothing in the logs that explains why.

Actually verify the migration ran. Check that proxy.ts exists at project root, the export is named proxy, and middleware.ts is deleted. Running the codemod and assuming it worked is not the same as checking. Manual upgrade with no codemod means the old file sits there silently doing nothing with zero warning.

Check the matcher every time you add a protected route. New route, check it falls inside the matcher pattern, check it appears in ROLE_ROUTES. Most auth gaps I've seen get introduced weeks after the initial proxy setup when someone adds a route and nobody goes back to verify coverage.

The proxy is the fast gate. It's essential and does its job well at the network boundary.

It can't answer ownership questions. It can't stop one user from seeing another user's data. And the forwarded header pattern has a real trust boundary issue on any route where the matcher has a gap.

Next post covers the Server Component authorization layer, roles versus permissions, why permissions need a database call that roles don't, and how the independent check at render time catches what the proxy structurally cannot.

Full implementation with all three layers: shubhra.dev/tutorials/nextjs-16-authentication-3-layer-security. The proxy setup in this post maps to Step 2 there. The getVerifiedUser utility above updates the Server Component pattern in Step 3 to close the header trust boundary gap.

Note: I use AI for editing and structure, but the technical substance is from my own work.

I Thought My Next.js 16 Auth Was Solid. One Afternoon Proved Otherwise.

Shubhra Pokhariya — Wed, 10 Jun 2026 07:04:58 +0000

A few months ago I was doing a final pre-release review on a client project before handing it over.

Protected routes were protected. Unauthenticated users got redirected. Tokens expired correctly. I had tested it three different ways and everything held up. I was confident enough to stop thinking about it.

Then I found something.

A user with a valid session, the right role, and a correct JWT could still request another user's invoice if they knew the ID. No error in the logs. No failed requests. The auth was technically correct at every layer I had actually built.

The problem was I had only built one layer and called it done.

That afternoon changed how I think about Next.js 16 authentication entirely. And I have been building it differently ever since.

One Thing to Check Before Writing a Line of Auth Code

If you are coming from Next.js 15, middleware.ts is deprecated in Next.js 16 and replaced by proxy.ts. Same location in your project, different filename, different exported function name. middleware.ts still works for Edge runtime use cases but will be removed in a future version.

// Before: middleware.ts
export function middleware(request: NextRequest) { ... }

// After: proxy.ts
export function proxy(request: NextRequest) { ... }

The auth-relevant change is the runtime. middleware.ts defaulted to Edge runtime, which had limited crypto support. Verifying JWTs in Edge required lighter libraries and sometimes workarounds depending on which algorithms your tokens used.

proxy.ts runs on Node.js runtime in Next.js 16. jose works completely. Any standard JWT library works. It removes the Node-crypto limitations that existed in the Edge runtime, which is a massive improvement for auth specifically.

# Handles the rename and all other Next.js 16 breaking changes
npx @next/codemod@canary upgrade latest

# Only the middleware migration if that is all you need
npx @next/codemod@canary middleware-to-proxy .

After running it: verify proxy.ts exists in your project root and the exported function is named proxy. Remove middleware.ts to avoid ambiguity. While it is still supported for Edge runtime, it is deprecated in Next.js 16 and the framework expects proxy.ts going forward.
Keeping both files can lead to confusion about which one is actually handling requests.

One important constraint: proxy.ts is designed for redirects, rewrites, header modifications, and direct responses. It is not intended for slow data fetching or full session management, and should not be used as your primary authorization layer. This is by design to keep the proxy focused on fast network boundary concerns.

Why proxy.ts Is Not Your Security Layer (Even Though It Looks Like One)

This is the thing almost every Next.js auth tutorial gets wrong. Not in an obvious way. In the way that passes all your tests and breaks in production.

proxy.ts runs at the network boundary before anything renders. It reads your session cookie, verifies the JWT, checks the role, and redirects or continues. Fast, essential, genuinely useful. Every auth setup needs it.

But it only sees URL patterns.

When it decided my user could access /dashboard/invoices, its job was done. It had no idea which specific invoice ID was in the URL, who owned that invoice, or whether the person requesting it had any right to see it. From the proxy's point of view, the URL matched, the role matched, the token was valid. Green light.

That gap is the invoice incident. The proxy was correct. It was just correct about the wrong thing.

// proxy.ts: role-based route protection, correct and valuable
const ROLE_ROUTES: Record<string, string[]> = {
  "/admin": ["admin"],
  "/dashboard": ["admin", "user", "moderator"],
}

// The proxy sees /dashboard/invoices/abc123 and approves it
// It has no way to know if abc123 belongs to this user
// Not a proxy bug. A category mismatch.

The proxy cannot answer ownership questions. Nobody can answer ownership questions from a URL pattern alone. You need the database for that. And the database is not where the proxy runs.

Treating proxy.ts as the complete security layer is not a configuration mistake. It is a mental model mistake. And it is the one almost every auth tutorial makes by stopping there.

The Check That Runs Even When Your Proxy Has a Gap

Server Components render when the page renders. That sounds obvious, but the implication is worth sitting with: Server Components run after the proxy and act as a second layer of enforcement. Even if a route slips past a misconfigured proxy matcher gap, this check still runs.

This is also where you catch the thing the proxy structurally cannot catch: permission-level decisions that depend on your database.

// app/dashboard/billing/page.tsx
import { headers } from "next/headers"
import { redirect } from "next/navigation"
import { getUserPermissions, getUserInvoices } from "@/lib/data"

export default async function BillingPage() {
  const headerStore = await headers()
  const userId = headerStore.get("x-user-id")

  // This check runs even if the proxy had a gap on this route
  if (!userId) {
    redirect("/login")
    return
  }

  // Role came from the JWT, fast, no DB call needed
  // Permissions need a DB call because they change more often than roles
  const permissions = await getUserPermissions(userId)

  if (!permissions.includes("billing:read")) {
    redirect("/unauthorized")
  }

  const invoices = await getUserInvoices(userId)
  return <BillingView invoices={invoices} />
}

The split between roles and permissions is intentional. Roles are stable enough to embed in a JWT. The proxy reads them without touching the database. Permissions change when you update access settings and you do not want to wait for a JWT to expire before that change takes effect. Roles in the proxy, permissions in the Server Component. That boundary matters.

The x-user-id header gets there because the proxy sets it before forwarding the request:

// Inside proxy.ts after JWT verification
const requestHeaders = new Headers(request.headers)
requestHeaders.set("x-user-id", payload.sub as string)
requestHeaders.set("x-user-role", role)

return NextResponse.next({
  request: { headers: requestHeaders },
})
// Headers go on the request, not the response
// Server Components read incoming request headers via headers()
// Setting them on the response sends them to the browser instead
// Your pages never see them if you get this backwards

I got this backwards the first time I wrote it. No error anywhere. The headers() call in the Server Component just returned null for both fields and the page redirected everyone to /login including fully authenticated admins. Spent an embarrassing amount of time on that one.

The Backstop That Would Have Caught the Invoice Bug No Matter What

Even if the proxy had a gap and the Server Component had a gap on the same day, this layer still holds.

Every data function that returns user-specific data takes a userId and uses it inside the query. Not as a convenience. As the actual access control.

// lib/data.ts

// This is what my data layer looked like before the incident
export async function getInvoice(invoiceId: string) {
  return db.query(
    "SELECT * FROM invoices WHERE id = $1",
    [invoiceId]
  )
}
// Anyone with any valid session could call this with any ID
// No error. No log entry. Just data returned to whoever asked.

// This is what it looks like now
export async function getInvoice(invoiceId: string, userId: string) {
  const invoice = await db.query(
    "SELECT * FROM invoices WHERE id = $1 AND user_id = $2",
    [invoiceId, userId]
  )

  if (!invoice) {
    throw new Error("Not found")
  }

  return invoice
}

The same error for "not found" and "not authorized" is intentional. Different errors let an attacker enumerate which IDs exist in your system. One generic error closes that information leak.

The ownership check lives inside the SQL. It cannot be misconfigured away. It cannot be missing from a route someone added last week. It cannot have a matcher gap. The authorization is in the query itself and the query runs every single time.

This is the layer that was missing from my app. The other two were correct. This one did not exist.

What All Three Layers Look Like on One Request

When an authenticated user hits /dashboard/invoices/abc123:

Request arrives

proxy.ts
  Reads auth_tokens cookie (written by your auth API on login)
  Verifies JWT (full Node.js runtime in Next.js 16, jose works completely)
  Checks role against ROLE_ROUTES
  Wrong role? Redirect to /unauthorized
  Correct role? Set x-user-id, x-user-role on request headers, continue

app/dashboard/invoices/[id]/page.tsx
  Reads x-user-id from forwarded headers, no re-verification needed
  Checks billing:read permission against DB
  Missing permission? redirect('/unauthorized')
  Has permission? Call getInvoice(id, userId)

lib/data.ts: getInvoice(invoiceId, userId)
  SELECT * FROM invoices WHERE id = $1 AND user_id = $2
  No row? throw new Error('Not found')
  Row exists? User owns it. Return data.

Component renders.

Three independent checks. A bug at any one of them does not open a door because the other two are still running.

One setup requirement worth knowing before you build this: the proxy reads the session from a cookie. If your auth client stores tokens in localStorage by default, the proxy cannot see them at all and will redirect every authenticated request straight to login. Make sure your auth setup writes tokens to a cookie. The proxy template in the full implementation reads a cookie named auth_tokens set on login.

The invoice incident had no bug in the proxy. No bug in the Server Component. One missing AND user_id = $2 in a data function. That was the whole thing.

The Mental Model in One Sentence

The proxy decides who can reach a route. The Server Component decides who can render a page. The data layer decides who can see a record.

All three are required. Any one of them alone will eventually have a gap. Two of them will eventually have a gap on the same day and you will be glad the third one exists.

The invoice incident was not a proxy failure. Not a Server Component failure. It was a missing data layer. The first two layers were correct. The third one did not exist.

That is the auth system most Next.js tutorials hand you. One layer. The other two are never mentioned.

This post is part of the Next.js 16 Auth: From Broken to Production-Safe series. The next post covers building the complete proxy.ts gate with working code: JWT verification with jose, the role routing config, the matcher pattern that most setups get wrong, and why the header forwarding direction breaks silently when you get it backwards.

The full implementation with all three layers, token refresh, Route Handler protection, and the complete Auth Guard client-side setup is at shubhra.dev/tutorials/nextjs-16-authentication-3-layer-security.

Has anyone else hit a data layer gap like this? I kept assuming the proxy covered everything until it very clearly did not. Curious how common this actually is across different projects.

After 7 Next.js 16 Caching Bugs, I Stopped Guessing and Built a System

Shubhra Pokhariya — Wed, 03 Jun 2026 05:09:01 +0000

There's a specific feeling you get after your third production caching incident.

It's not panic. It's worse than panic. It's that quiet realisation that you fixed the last bug correctly, and you still have no idea where the next one is hiding.

After the 7 silent caching bugs post, a pattern kept coming up in the comments. Everyone understood what was breaking, but not what the correct setup should look like. This is that answer.

Not theory. The actual system I use now, after getting burned enough times to understand why each piece exists.

The first problem: tag strings written from memory in different files

Most silent cache bugs in Next.js 16 start here. Not because anyone is being careless. Because there is nothing stopping two people from writing two different strings that should be the same.

Developer A writes the data function on Monday:

async function getProducts() {
  'use cache'
  cacheTag('product-list')
  return db.query('SELECT * FROM products')
}

Developer B writes the mutation two weeks later in a different file:

export async function createProduct(data: ProductData) {
  await db.query('INSERT INTO products ...', [...])
  revalidateTag('products', 'max')
}

product-list and products. Two different strings. Zero errors from TypeScript, zero warnings from Next.js. The product list never refreshes after a new product is created and nobody knows why until someone reads both files at the same time.

This is Bug 3 from the previous post. I kept hitting variations of it across different parts of the codebase even after I knew about it, because knowing about a problem and having something that prevents it are not the same thing.

The fix is one file that owns all your tag strings:

// lib/tags.ts
export const tags = {
  product: (id: string | number) => `product-${id}`,
  user: (id: string | number) => `user-${id}`,
  productList: 'products',
  userList: 'users',
  navigation: 'navigation',
} as const

Now both files import from tags. A typo is a TypeScript compile error. The string mismatch bug cannot happen. Everyone on the team gets autocomplete instead of muscle memory.

// data function
cacheTag(tags.productList)

// mutation — same import, same string, guaranteed
revalidateTag(tags.productList, 'max')

This is the single change that removed the most bugs from my codebase, by far. Set it up before you write a single cached function on a new project.

The second problem: three different places to invalidate cache, three different correct APIs

This is where I see the most confusion, including in my own early code. The API you reach for depends entirely on where you're calling from and what the user needs to see. Get it wrong and you either throw at runtime or silently give someone stale data.

Here is how I think about it now:

Inside a Server Action where the user who just made a change needs to see it immediately:

'use server'
import { updateTag, revalidateTag } from 'next/cache'

export async function updateProductPrice(id: string, newPrice: number) {
  await db.query('UPDATE products SET price = $1 WHERE id = $2', [newPrice, id])

  updateTag(tags.product(id))               // acting user sees fresh data right away
  revalidateTag(tags.product(id), 'max')    // everyone else gets SWR update
  revalidateTag(tags.productList, 'max')    // product list refreshes too
}

The order matters here. updateTag runs first. This is what prevents the admin from clicking save, navigating back to the product page, and seeing the old price. That looks like the save failed. It causes people to click save again. updateTag fixes it.

updateTag is Server Actions only. Calling it anywhere else throws at runtime.

Inside a Route Handler (webhooks, external services):

// app/api/webhooks/stripe/route.ts
import { revalidateTag } from 'next/cache'

export async function POST(req: Request) {
  const event = await parseStripeWebhook(req)
  if (event.type === 'price.updated') {
    revalidateTag(tags.productList, { expire: 0 })
  }
  return new Response('ok', { status: 200 })
}

updateTag is not available in Route Handlers. { expire: 0 } is the equivalent for immediate expiry here. This is what you want for webhooks where a third-party system just told you something changed.

Background updates where a brief stale window is fine:

revalidateTag(tags.productList, 'max')

Stale-while-revalidate. Users get a fast cached response while fresh data loads behind the scenes. For most content this is exactly right. An admin publishes a new post, readers might see the old list for a moment, that is usually acceptable.

Here is the whole thing as a decision table:

Situation	Use
User edits their own data and needs to see it immediately	`updateTag` then `revalidateTag`
Webhook fires, third-party service needs immediate consistency	`revalidateTag(tag, { expire: 0 })`
Background refresh, brief stale window is acceptable	`revalidateTag(tag, 'max')`

Write this down somewhere your team can see it. Saves a lot of "why is the user seeing old data after saving" conversations.

The third problem: the PPR split is invisible by default

With cacheComponents: true, Next.js uses Partial Prerendering. Your page has a static shell that renders instantly from cache and dynamic holes that stream in after. The performance win is real. The problem is that what ends up in the shell versus what ends up as a dynamic hole is not obvious until something behaves wrong.

One component with cacheLife('seconds') gets quietly excluded from the static shell. A cookies() call inside a cached scope throws at build time with "Uncached data was accessed outside of Suspense" and gives you no component name, no file path, nothing useful. A dynamic component added without a Suspense boundary pushes part of the page out of the shell.

The way I stopped guessing about this is to document intent at the component level:

// components/UserCart.tsx
export const boundary = {
  name: 'UserCart',
  isDynamic: true,
  reason: 'Reads user session cookie — different per user',
}

Then in the page that uses it, I reference that intent explicitly:

export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params

  // UserCart is dynamic — must be in Suspense or it breaks the static shell
  return (
    <div>
      <ProductDetails id={id} />       {/* cached, part of static shell */}
      <RelatedProducts id={id} />      {/* cached, part of static shell */}
      <Suspense fallback={<CartSkeleton />}>
        <UserCart productId={id} />    {/* dynamic, streams in after */}
      </Suspense>
    </div>
  )
}

The cached components look like this:

async function ProductDetails({ id }: { id: string }) {
  'use cache'
  cacheLife('hours')
  cacheTag(tags.product(id))

  const product = await db.query(
    'SELECT * FROM products WHERE id = $1', [id]
  )
  return <article>...</article>
}

The dynamic component has no 'use cache' at all:

async function UserCart({ productId }: { productId: string }) {
  const cookieStore = await cookies()
  const userId = cookieStore.get('user-id')?.value
  const cartItem = await db.query(
    'SELECT * FROM cart WHERE user_id = $1 AND product_id = $2',
    [userId, productId]
  )
  return cartItem ? <InCartButton /> : <AddToCartButton />
}

Static shell hits the user instantly. Cart streams in after. The split is intentional and documented, not whatever survived the algorithm.

One more thing on this: never call cookies(), headers(), or draftMode() inside a 'use cache' scope. Read them outside, pass the values as props. Those values become part of the cache key automatically — different users produce separate cache entries without you doing anything extra.

The fourth problem: cold starts hurt the first visitor after every deploy

This one is separate from the bugs but connects to the same goal. Your caching is set up correctly. You deploy. The first visitor hits the page and every cached function runs from scratch sequentially because the cache is empty.

PPR is fast once the cache is warm. That first request after a deploy is not.

The fix is React's cache() for request-level deduplication. Fire all your data fetches in parallel at the top of the page before any component needs them:

import { cache } from 'react'
import { getProductById, getRelatedProducts } from '@/lib/data'

const prefetch = {
  product: cache(getProductById),
  related: cache(getRelatedProducts),
}

export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params

  void prefetch.product(id)
  void prefetch.related(id)

  return (
    <div>
      <ProductDetails id={id} />
      <RelatedProducts id={id} />
      <Suspense fallback={<CartSkeleton />}>
        <UserCart productId={id} />
      </Suspense>
    </div>
  )
}

Both fetches fire immediately in parallel. Child components that call the same functions get deduplicated results from React's cache(). If a prefetch fails it fails silently. It is an optimisation, not a requirement. The actual fetching in child components still works.

The distinction worth knowing: React's cache() deduplicates within a single request. 'use cache' persists across requests. You need both, they solve different problems.

What the full system looks like

One tags file. Everyone imports from it. A typo is a compile error, not a production incident.

A clear decision for invalidation context: Server Action with a user waiting for their change uses updateTag first, then revalidateTag. Route Handler uses revalidateTag with { expire: 0 }. Background broadcast uses revalidateTag with 'max'.

Dynamic components documented and always wrapped in Suspense. The static shell is explicit, not accidental.

Prefetch fired in parallel at the top of heavy pages so the first visitor after a deploy is not the one paying the cold start cost.

None of this is complicated once you have it written down. The hard part was figuring out that I needed all of it, which took enough production bugs to see the pattern.

The earlier posts in this series cover how I got here. Building the debugger when development was a black box. The seven bugs that compile and break silently. The upgrade breaks that the build never warns you about.

If you want the full migration reference, I wrote that at shubhra.dev/tutorials/nextjs-16-cache-components.

I kept hitting these edge cases often enough that I eventually pulled the whole system into a single utility. The Cache Pro Kit is the production version of everything in this post. Type-safe tag registry, safeRevalidate that blocks the single-arg call at compile time, serverActionInvalidate that enforces the correct order, routeHandlerInvalidate so updateTag in a Route Handler is impossible. One file, drop into lib/.

What does your caching setup look like right now? Have you hit any of these in your own projects?

Next.js 16 Broke My App in 4 Places and None of Them Threw an Error

Shubhra Pokhariya — Wed, 27 May 2026 08:32:54 +0000

The CI was green.

Build passed. No TypeScript errors. No warnings. Everything looked clean. I clicked deploy and went to make tea.

Came back, opened staging, and things were broken in ways that made no sense. A redirect wasn't working. Lint had silently disappeared from the build pipeline. One API route was throwing on the very first real request. And a revalidation call I'd written two weeks earlier was running but doing nothing.

Not one of these showed up during the build. Everything looked completely fine until it wasn't.

This is what actually happened during my Next.js 16 upgrade, and what to check before you ship yours.

1. `middleware.ts` stopped running and told me nothing

My middleware file was fine. It compiled. The export was valid. TypeScript was happy.

After upgrading to Next.js 16, it just stopped running on requests. No error. No deprecation warning. No sign of anything wrong in the terminal. The file was simply ignored.

What happened: Next.js 16 replaced middleware.ts with proxy.ts. Same location in your project. Different filename. Different exported function name.

// Before: middleware.ts
export function middleware(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

// After: proxy.ts
export function proxy(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

That's the whole change. File rename, function rename. But because the old file didn't throw anything, I assumed it was still running. I only caught it because a redirect I expected wasn't happening and I spent way too long looking at the wrong thing.

One thing to know: if you need edge runtime behavior specifically, middleware.ts still exists for that use case. In my case, the logic I had there stopped running after the upgrade. Renaming the file and export fixed it immediately. The codemod handles this automatically. But if you manually upgraded the package without running it, or if it missed a file, this one is completely invisible.

Before you ship: rename the file, rename the export, test a route that depends on it.

2. `revalidateTag('products')` compiled, deployed, and silently did the wrong thing

During the migration I wrote this:

revalidateTag('products')

One argument. Totally normal in Next.js 15. I'd written it a couple of weeks earlier and hadn't thought about it since.

In Next.js 16, the single-argument form is deprecated and produces a TypeScript error. But only if your tsconfig is in strict mode. Mine wasn't. It had been set up on an older project years ago and never touched.

So it compiled. It deployed. It ran. And it fell back to legacy invalidation behavior instead of the new SWR-based system. Pages weren't reflecting mutations. No error anywhere, just stale data that I attributed to other things for longer than I should have.

The fix is just adding the second argument:

revalidateTag('products', 'max')          // SWR, the recommended default
revalidateTag('products', { expire: 0 })  // Immediate expiry, for webhooks

The codemod (npx @next/codemod@canary upgrade latest) handles this. But if you wrote any revalidation calls after upgrading, or if the codemod missed a file, check manually.

The real fix is turning on strict mode in your tsconfig. That one change makes this a compile error instead of a silent runtime problem:

{
  "compilerOptions": {
    "strict": true
  }
}

Do it before anything else.

3. `next lint` disappeared and my CI kept saying it passed

This one sounds minor. It wasn't.

next lint is completely removed in Next.js 16. Not deprecated. Not changed. Gone. The eslint option in next.config.ts is also gone. next build no longer runs linting automatically.

My CI was configured to run next lint as a step. After the upgrade, that command no longer existed. Depending on how your CI handles missing commands, it might fail loudly or it might just succeed silently and move on. Mine moved on.

So I was shipping code with no linting running, and the CI was reporting green. I only noticed when an obvious issue slipped through that I expected lint to catch.

The migration is to run ESLint directly:

"scripts": {
  "lint": "eslint .",
  "lint:fix": "eslint . --fix"
}

The codemod creates eslint.config.mjs and updates your package.json scripts. But your CI config is a separate file the codemod does not touch. Check both places.

4. One component was still reading `params` synchronously

The codemod updated most of my pages correctly. But I had a layout file it missed. The component was accessing params directly without awaiting it, which is fine in Next.js 15 but wrong in 16 where params is now a Promise.

// Before — Next.js 15
export default function Layout({ params }: { params: { id: string } }) {
  const id = params.id
}

// After — Next.js 16
export default async function Layout({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
}

This one did throw, but only on the first real request to that route in staging, not during the build. The build passed completely clean.

If you have layouts, pages, or route handlers, search the whole codebase for direct params. access and check that every one has been updated. Same goes for searchParams, cookies(), headers(), and draftMode(). All async now, all need awaiting.

The pattern that connects all four

None of these are caching bugs. They're upgrade bugs. The kind where the build passes, the code is technically valid, and the wrong behavior only shows up under a specific condition: a real redirect being triggered, a mutation needing to reflect, a lint issue reaching review, a specific route being hit.

The codemod gets most of this. Run npx @next/codemod@canary upgrade latest before you change anything else. Then check three things manually: grep for any revalidateTag( with a single argument, check your CI config for next lint, and turn on strict TypeScript. Those three cover most of what the codemod can miss.

If you're already past the upgrade and dealing with caching behavior specifically, the previous posts in this series cover that. The debugger I built to make cache behavior visible during development and the seven bugs that compile clean and break silently in production.

I also have a full step-by-step migration guide with before/after comparisons at shubhra.dev/tutorials/nextjs-16-cache-components if you want the complete reference.

Which of these hit you? Or something I didn't mention here?

7 Next.js 16 Caching Bugs That Compile Fine and Break Silently in Production

Shubhra Pokhariya — Thu, 21 May 2026 12:06:06 +0000

I lost hours debugging a Next.js 16 caching issue that had no error, no warning, and only showed up in production.

The Next.js 16 caching model is genuinely good. But it introduces a class of bugs that are harder to detect than anything in previous versions: bugs that look correct, compile without errors, deploy successfully, and then silently misbehave in production.

These are the most common ones I've seen across real projects. Every one comes from real production incidents.

(Assumes you have cacheComponents: true enabled in next.config.ts.)

This is a follow-up to my previous post where I built a dev-only debugger to surface these issues during development. That tool helps you detect them. This post breaks down the exact failure cases behind those warnings.

Bug 1: `'use cache'` on the Wrapper Instead of Inside the Function

// This looks cached. It is not.
export const getProducts = someWrapper(async function() {
  'use cache'
  cacheLife('hours')
  return db.query('SELECT * FROM products')
})

The 'use cache' directive tells the Next.js compiler to treat that function as a cache boundary. When you wrap it, the compiler sees the wrapper as the entry point. The inner function may be cached, but the wrapper becomes the execution boundary, so you still end up running it on every request.

No error. No warning. Just a function running on every request when it should be cached.

Fix:

async function _getProducts() {
  'use cache'
  cacheLife('hours')
  cacheTag('products')
  return db.query('SELECT * FROM products')
}

// Wrapper receives the already-cached function
export const getProducts = someWrapper(_getProducts)

The rule is simple: 'use cache' lives inside the data function, never on anything that wraps it.

Bug 2: Deprecated `revalidateTag` That Compiles and Uses Legacy Behavior

// Next.js 15: correct
// Next.js 16: TypeScript error, silently uses legacy behavior in loose tsconfig
revalidateTag('products')

In Next.js 16, revalidateTag without a second argument is deprecated and produces a TypeScript error. But if your tsconfig is not in strict mode (common in older projects), it compiles cleanly and falls back to legacy invalidation behavior instead of the new SWR-based system.

Pages stop reflecting mutations. No error anywhere.

Fix:

revalidateTag('products', 'max')         // SWR, recommended for most content
revalidateTag('products', { expire: 0 }) // Immediate expiry for webhooks/payments

Run npx @next/codemod@canary upgrade latest during your migration, it handles this automatically. But check your tsconfig strictness regardless.

Bug 3: Tag String Mismatch Across Files

// lib/data.ts -- written by developer A
async function getProducts() {
  'use cache'
  cacheTag('product-list')  // Tag is 'product-list'
  return db.query('...')
}

// app/actions/products.ts -- written by developer B
export async function createProduct(data: ProductData) {
  await db.query('INSERT INTO products ...', [...])
  revalidateTag('products', 'max')  // Different string, invalidates nothing
}

Two different strings. Zero errors. The product list never refreshes after a new product is created. Users see stale data until cacheLife expires on its own.

Fix:

// lib/tags.ts -- one source of truth
export const tags = {
  products: 'product-list',
  product: (id: string) => `product-${id}`,
  user: (id: string) => `user-${id}`,
} as const

// Both files import from tags
cacheTag(tags.products)
revalidateTag(tags.products, 'max')

Tag typos become TypeScript errors. The string mismatch bug becomes structurally impossible.

Bug 4: Server Action Mutation Where the Acting User Sees Stale Data

'use server'
export async function updateProductPrice(id: string, newPrice: number) {
  await db.query('UPDATE products SET price = $1 WHERE id = $2', [newPrice, id])
  revalidateTag(`product-${id}`, 'max')
}

revalidateTag with any named profile uses stale-while-revalidate. It marks the cache as stale. The next request still gets the cached version while fresh data loads in the background.

For the admin who just clicked save, that means they navigate to the product page and see the old price. Looks like the save failed. Causes confusion and duplicate mutations.

Fix:

'use server'
import { revalidateTag, updateTag } from 'next/cache'

export async function updateProductPrice(id: string, newPrice: number) {
  await db.query('UPDATE products SET price = $1 WHERE id = $2', [newPrice, id])
  updateTag(`product-${id}`)            // Acting user sees change immediately
  revalidateTag(`product-${id}`, 'max') // Everyone else gets SWR
  revalidateTag('products', 'max')      // Product list also refreshes
}

updateTag expires the cache entry immediately. The next request waits for fresh data. The admin sees their change. Everyone else gets the fast SWR treatment.

Constraint: updateTag only works inside Server Actions. In Route Handlers, use revalidateTag(tag, { expire: 0 }) instead.

Bug 5: `updateTag` in a Route Handler

// app/api/webhooks/stripe/route.ts
import { updateTag } from 'next/cache'

export async function POST(req: Request) {
  const event = await parseStripeWebhook(req)
  if (event.type === 'price.updated') {
    updateTag('products')  // Throws at runtime
  }
  return new Response('ok', { status: 200 })
}

This compiles. It deploys. On the first real webhook call from Stripe, it throws at runtime. updateTag only works inside Server Actions. Calling it anywhere else throws.

Fix:

import { revalidateTag } from 'next/cache'

export async function POST(req: Request) {
  const event = await parseStripeWebhook(req)
  if (event.type === 'price.updated') {
    revalidateTag('products', { expire: 0 })  // Immediate expiry in Route Handlers
  }
  return new Response('ok', { status: 200 })
}

Bug 6: Short `cacheLife` That Silently Affects PPR

async function LiveStockStatus({ productId }: { productId: string }) {
  'use cache'
  cacheLife('seconds')  // Seems right for live stock data
  cacheTag(`stock-${productId}`)
  return fetchStockLevel(productId)
}

cacheLife('seconds'), revalidate: 0, and expire under 5 minutes are automatically excluded from the PPR static shell. They become dynamic holes that run at request time.

One component with cacheLife('seconds') can push parts of the page out of the static shell and turn them into request-time work. No warning. The page still works. It just becomes fully dynamic without any obvious signal.

Fix, if the data can tolerate a short delay:

cacheLife('minutes')  // Now included in the static shell

Fix, if it genuinely needs to be live:

// Parent page
<Suspense fallback={<StockSkeleton />}>
  <LiveStockStatus productId={id} />  {/* Streams in after static shell */}
</Suspense>

The second approach is the correct PPR pattern for truly dynamic data. The static shell renders instantly and the live data streams in after.

Bug 7: Runtime API Inside a Cached Scope

async function UserHeader() {
  'use cache'
  const cookieStore = await cookies()  // Throws at build time
  const user = await getUser(cookieStore.get('user-id')?.value)
  return <div>{user.name}</div>
}

cookies(), headers(), and draftMode() are runtime APIs. They read request-specific data. They cannot live inside a 'use cache' scope because cached output is stored and replayed across requests.

This one at least throws at build time with "Uncached data was accessed outside of Suspense". But the error gives you no component name, no file path, and no useful stack trace. You get to play binary search across your codebase to find it.

Fix:

// Read runtime values OUTSIDE the cached scope
async function UserHeader() {
  const cookieStore = await cookies()
  const userId = cookieStore.get('user-id')?.value
  return <CachedUserProfile userId={userId} />
}

// Pass the VALUE as a serializable prop to the cached component
async function CachedUserProfile({ userId }: { userId?: string }) {
  'use cache'
  cacheLife('hours')
  cacheTag(`user-${userId}`)
  if (!userId) return <GuestGreeting />
  const user = await getUser(userId)
  return <div>{user.name}</div>
}

userId is a string so it becomes part of the cache key automatically. Different users produce different cache entries without any manual key construction.

The Common Thread

None of these have good error messages. Five of the seven compile and deploy without complaint. The other two throw, but either without enough information to find the cause quickly or only after the first real production request.

The pattern across all of them is the same: the new caching model requires explicit correctness. When you get something wrong, it does not always tell you.

If you are in the middle of a Next.js 16 migration and want to catch these during development rather than in production, I ended up building a free dev-only debugger that logs cache misses, dynamic holes, missing tags, and deprecated invalidation calls directly in your terminal. Zero production cost, one .tsx file: Next.js cache debugger.

And if you want these patterns enforced at the type level so the wrong call is a compile error rather than a runtime surprise, the production enforcement layer is Cache Pro Kit.

Have you run into any of these? Or something even stranger? I'm curious what the distribution looks like across different kinds of projects.

I built a free debugger because Next.js 16 'use cache' was completely invisible during development

Shubhra Pokhariya — Tue, 19 May 2026 10:29:28 +0000

I spent an afternoon debugging a component that kept re-fetching on every single request.

It had 'use cache' right there in the code. I was confident it was working. It wasn't.

The problem was placement. 'use cache' was on the wrapper function, not inside the actual data function. That one mistake makes Next.js ignore the directive entirely. No error, no warning, nothing in the terminal. Just a function running on every request when it should have been cached.

Another time I wrote this in a Server Action during a Next.js 16 migration:

revalidateTag('products')

It compiled. It deployed. Pages stopped reflecting mutations. Calling revalidateTag without a second argument is a TypeScript error in Next.js 16, but the runtime fell back to legacy behaviour silently. I only caught it when users started reporting stale data.

Next.js 16's new caching model is genuinely great. But during development it is a complete black box. You add the directive, you assume it works, and you only find out otherwise when something breaks in production.

So I built a small dev-only toolkit to make it visible.

What it catches

1. Silent cache misses

If a function runs more than once with identical arguments, you see this immediately:

[cache-debug] ⚠  POSSIBLE CACHE MISS - RE-EXECUTION WITH SAME ARGS
  fn:   getProductById
  args: ["prod-123"]
  This function ran 2 times with identical args.
  If you expect caching: check 'use cache' is inside this function, not the wrapper.

That warning would have saved me that entire afternoon.

2. Dynamic holes from short cacheLife

cacheLife('seconds') silently excludes a component from the PPR static shell. It becomes fully dynamic. No warning anywhere, just a slower page that you cannot explain.

[cache-debug] ⚡ DYNAMIC HOLE WARNING
  fn:       getLivePrice
  cacheLife 'seconds' is short-lived (< 5 minutes or revalidate: 0).
  Next.js 16 automatically EXCLUDES this from the PPR static shell.
  This function will run at request time, it is NOT prerendered.
  Fix: Use 'minutes' or longer if you want it in the static shell.

3. Missing cacheTag

A cached function with no cacheTag() can only expire by time. You cannot revalidate it on demand. Easy to miss when moving fast, painful to discover later.

[cache-debug] 🏷  MISSING cacheTag WARNING
  fn:   getProductById
  No cacheTag() found. This function cannot be invalidated on demand.
  It will only expire when cacheLife runs out.
  Fix: Add cacheTag('your-tag') inside the function.

4. Deprecated revalidateTag

In Next.js 16, revalidateTag('tag') without a second argument is a TypeScript error. The logInvalidation helper catches it before your CI does:

[cache-debug] ✗  DEPRECATED revalidateTag - MISSING SECOND ARG
  tag:     products
  revalidateTag('products') without a profile is deprecated in Next.js 16.
  Fix: revalidateTag('products', 'max')

5. updateTag outside a Server Action

Calling updateTag outside a Server Action throws at runtime. The toolkit catches it at dev time before it reaches production.

6. Repeated fetches

detectRepeatedFetch surfaces the same URL being hit multiple times in one render. Usually means a cache layer is missing entirely.

How to use it

Step 1: Enable in .env.local

CACHE_DEBUG=true

Do not add this to .env.production. The NODE_ENV guard already ensures it is off in production, but keeping env files clean is good practice.

Step 2: Wrap your cached functions

The 'use cache' directive must stay inside the original function. withCacheDebug is a regular wrapper and cannot be a cache boundary. If you put 'use cache' on the wrapper, the instrumentation gets cached instead of the data function, which is exactly the mistake the POSSIBLE CACHE MISS warning is designed to catch.

import { cacheLife, cacheTag } from "next/cache";
import { withCacheDebug } from "@/lib/cache-debug";

async function _getProductById(id: string) {
  "use cache";
  cacheLife("hours");
  cacheTag(`product-${id}`, "products");
  return db.query("SELECT * FROM products WHERE id = $1", [id]);
}

export const getProductById = withCacheDebug(_getProductById, {
  name: "getProductById",
  cacheLife: "hours",
  tags: ["product-{id}", "products"],
});

const product = await getProductById("prod-123");

Zero API change. The exported function works exactly the same everywhere you already call it.

Step 3: Log invalidation calls in Server Actions

"use server";
import { revalidateTag, updateTag } from "next/cache";
import { logInvalidation } from "@/lib/cache-debug";

export async function updateProductPrice(id: string, newPrice: number) {
  await db.query("UPDATE products SET price = $1 WHERE id = $2", [newPrice, id]);

  logInvalidation("updateTag", `product-${id}`, {
    isServerAction: true,
    context: "admin price update",
  });
  updateTag(`product-${id}`);

  logInvalidation("revalidateTag", "products", {
    profile: "max",
    isServerAction: true,
    context: "admin price update",
  });
  revalidateTag("products", "max");
}

Honest limitations

Process-scoped. Execution maps reset on cold start. In serverless environments each invocation may be a fresh process, so you will only see re-execution data within the same warm instance. For local dev with a long-running server it works exactly as intended.
Best-effort concurrency. Under concurrent rendering with identical args, both calls may log FIRST RUN rather than a miss. Detection does not affect correctness.
Cannot inspect Next.js internals. The debugger counts executions to detect likely misses. It cannot read Next.js's internal cache store directly.

None of these affect production because the tool is not present there.

At a glance

What it detects	Without this tool
FIRST RUN / CACHE MISS / NEW KEY	Not visible
Dynamic hole from short cacheLife	Not visible
Missing cacheTag	Not visible
Deprecated revalidateTag	TypeScript error, easy to miss
updateTag outside Server Action	Runtime throw
Repeated fetches in one render	Not visible

Zero external dependencies. TypeScript 5.0+ with strict mode. Next.js 16 only -- updateTag does not exist in Next.js 15. Double-gated on NODE_ENV === 'development' AND CACHE_DEBUG=true so nothing ships to production. No overhead, no bundle impact.

Get it

Free forever, one .tsx file: shubhra.dev/snippets/nextjs-use-cache-debugger

If you want the production enforcement layer that pairs with this -- type-safe tag registry, safeRevalidate that blocks the deprecated single-arg call at compile time, serverActionInvalidate that enforces the correct invalidation order -- that is the Cache Pro Kit.

If you are new to the Next.js 16 caching model and want to understand what 'use cache', cacheLife, and cacheTag are actually doing before using this toolkit, the practical migration guide covers the full picture. There is also a 15-question quiz if you want to test your understanding.

If you are in the middle of a Next.js 16 caching migration and something is behaving unexpectedly, this will make it visible. What has been the most frustrating or confusing part of the new caching model for you?

Lighthouse Said It Was Fast. My Users Kept Clicking the Same Button.

Shubhra Pokhariya — Wed, 06 May 2026 09:46:33 +0000

The bug wasn’t performance. It was silence.

I ran into this while building a Next.js dashboard.

There was a button that triggered a report generation flow. Some client-side processing, then an API call.

Lighthouse looked great. API response was around 80ms.

But session recordings told a different story.

Users were clicking the button 3 to 5 times in a row.

No errors in logs. No failed requests. Everything technically worked.

So I watched one of the recordings more carefully.

The moment the user clicked, nothing changed on screen.

No loading state.
No disabled button.
No visual feedback at all.

The UI looked exactly the same before and after the click.

That was the issue.

80ms response, zero perceived response

The backend was fast.

The interface just didn’t acknowledge the interaction.

From the user’s point of view, the click didn’t go through.

So they clicked again.

And again.

Not because they were impatient. Because the UI stayed silent.

Where most of us focus (and where it falls short)

We spend a lot of time optimizing load performance.

FCP, LCP, bundle size, Lighthouse scores. All worth caring about.

But most of the time a user spends on your app happens after the page has loaded.

That’s where trust is decided. In the interactions.

The 200ms line

There’s a threshold that shows up consistently in real usage.

If the UI responds within roughly 100 to 200ms, it feels instant.

Between 200 and 500ms, the delay becomes noticeable.

Beyond that, people start questioning whether their action worked.

A slow app is frustrating. An app that feels unresponsive gets abandoned.

What INP actually measures

INP (Interaction to Next Paint) focuses on one thing:

How long it takes for the user to see a response after they interact.

Not when your API returns.
Not when your function finishes.

When something visibly changes on the screen.

That’s what closes the loop.

The fix was not “make it faster”

The fix was: acknowledge the interaction immediately.

Instead of doing all the work first:

button.addEventListener("click", async () => {
  await processData();
  await syncWithServer();
  setLoading(false);
});

Flip it:

button.addEventListener("click", async () => {
  setLoading(true); // immediate visual feedback

  await scheduler.yield(); // let the browser paint

  await processData();
  await scheduler.yield();

  await syncWithServer();

  setLoading(false);
});

If scheduler.yield() is not available yet in your environment, a simple fallback works:

const yieldToMain = () => new Promise((r) => setTimeout(r, 0));

Same total work. Same total time.

Completely different experience.

Users stopped clicking multiple times.

The pattern you already use

You’ve seen this in every modern app.

You tap like. It updates instantly. The server confirms later.

That’s optimistic UI.

Here is the same idea in a simple form:

async function handleLike(postId) {
  setLiked(true);
  setCount((c) => c + 1);

  try {
    await api.like(postId);
  } catch {
    setLiked(false);
    setCount((c) => c - 1);
  }
}

In React and Next.js setups, this maps cleanly to useOptimistic and Server Actions.

The idea stays the same:

Show the result immediately. Reconcile in the background.

Why this matters more than Lighthouse 100

Lighthouse runs in controlled conditions.

Your users don’t.

They’re on slower devices, switching tabs, running background apps, dealing with network jitter.

You can ship a perfect score and still have interactions that feel off.

INP exposes that gap.

If you want to go deeper

This bug was the entry point for me.

I ended up breaking this down properly across INP, optimistic UI, task yielding, and how this fits into modern Next.js setups like Server Actions and streaming.

I wrote it up in detail here:
https://shubhra.dev/tutorials/performance-first-ui-mastery-guide-2026

That one goes deeper into how to actually implement this in real apps. This post is just the moment where the problem becomes obvious.

A quick way to test this

While working through this, I built a small quiz to check if I actually understood the idea or was just agreeing with it.

Here’s one of the questions:

A user clicks a button.
The server responds in 80ms.
They click four more times.

What actually failed?

Most people still go to backend performance first.

If that was your instinct too, you’ll probably find the rest useful:

https://shubhra.dev/quiz/performance-first-ui

It’s short. Focused on real interaction problems. No trick questions.

One practical takeaway

Next time you write a click handler, check the order:

Does something change on screen immediately?
Or does all the work happen before the user sees anything?

That one decision is often the difference between a UI that feels fast and one that feels broken.

If you’ve run into this in your own apps, I’m curious what caused it and how you approached it.

Why Most React Infinite Scroll Hooks Fail in Production (and the One That Fixed It for Me)

Shubhra Pokhariya — Thu, 30 Apr 2026 11:28:52 +0000

I used to believe infinite scroll was one of the simplest features to implement.

Fetch data → append to a list → load more on scroll.

Easy, right?

That’s exactly how most tutorials show it.

And honestly… it works.

Until it doesn’t.

The Bug That Changed Everything

One bug completely changed how I think about infinite scroll.

A user changed a filter → the list reset → new data loaded.

Everything looked correct.

Then a couple of seconds later…

the old results came back and overwrote the new ones.

No errors. No warnings.

Just silently broken UI.

What actually happened?

A slow request from the previous state finished late and updated the UI with stale data.

That was the moment I realized:

Infinite scroll doesn’t break in demos.It breaks with real users, real timing, and real networks.

Where Things Start Falling Apart

After that, I started noticing the same issues again and again:

Stale requests overwriting fresh data after reset
Retry logic fetching the wrong page
IntersectionObserver continuing to fire after errors
Duplicate requests in React Strict Mode
Loading states that never resolve

These problems rarely show up locally.

But in production, they show up fast.

What I Actually Needed

Not another demo.

Something I could trust in a real app.

So I built a hook around one idea:

Control the async flow. Don’t just “load more data”

What This Hook Handles

✔ Cancels stale requests (no overwrite bugs)
✔ Smart retry logic (correct page every time)
✔ Proper observer cleanup (no leaks)
✔ React 18+ Strict Mode safe
✔ Clear initial vs pagination loading states
✔ Manual loadMore, reset, and retry
✔ Zero dependencies

Basic Usage

const {
  items,
  isInitialLoading,
  hasMore,
  error,
  loadMoreRef,
  retry,
  reset
} = useInfiniteScroll({
  fetchFn: async (page, signal) => {
    const res = await fetch(`/api/posts?page=${page}`, { signal });
    return res.json();
  },
  pageSize: 20,
});
return (
  <div>
    <ul>
      {items.map((item) => (
        <li key={item.id}>{item.title}</li>
      ))}
    </ul>

    {/* Sentinel element */}
    <div ref={loadMoreRef} />

    {error && <button onClick={retry}>Retry</button>}
  </div>
);

Real Use Case: Reset on Filter Change

This is where most bugs happen.

useEffect(() => {
  reset(); // cancels old request + reloads safely
}, [filter]);

Without proper handling, this is exactly where stale data bugs appear.

Why AbortController Matters So Much

Before using it:

old requests still resolved
stale data overwrote the UI

After using it:

old requests get cancelled immediately
they never reach your state

That single change removes an entire class of bugs.

One Honest Note

This hook handles most real-world issues.

But for very large lists, you should still use virtualization
(like react-window or tanstack/virtual).

Infinite scroll solves loading.

Virtualization solves rendering.

Try It Yourself

You can grab the full hook here:

👉 https://shubhra.dev/snippets/use-infinite-scroll

MIT licensed
free to copy and modify
built for real production cases

Final Thought

I didn’t build this because infinite scroll is hard.

I built it because the small edge cases are what break real products.

Slow APIs. Fast users. Overlapping requests.

That’s where things actually fall apart.

Curious - what broke for you?

Have you ever hit a weird infinite scroll bug in production?

Something like:

duplicate data
stale UI
loading that never stops

Would genuinely love to hear what you ran into.

I Turned My Blog Into a Full Developer Platform (Tutorials + Snippets + Quizzes + Tools)

Shubhra Pokhariya — Tue, 28 Apr 2026 12:25:37 +0000

I’ve been working on building a developer platform with tutorials, reusable code snippets, interactive quizzes, and practical tools. This post shares what changed and what I’m building now.

For the past few months, I’ve been a little quiet here.

If you’ve been active on Dev.to regularly, you probably noticed I wasn’t reading as many posts, commenting, or sharing like I used to. And honestly, I missed that.

This community has always been one of my favorite places to learn and grow. Reading how others think, build, and solve problems has helped me a lot in my own journey.

So stepping away from that wasn’t easy.

Why I Went Quiet

I reached a point where I felt like just writing blog posts wasn’t enough for me anymore.

Don’t get me wrong, I still love writing. But I kept thinking:

What if I could make something more useful than just articles?

Something that helps people not only read, but also:

try things quickly
test their understanding
and actually use code in real projects

That idea stayed in my mind for a while.

And instead of talking about it, I decided to just build it.

What I’ve Been Working On

I took my simple blog and slowly turned it into something more complete.

Now it’s not just posts. It includes:

Tutorials that go step by step

Here’s how one of the tutorials looks:

Small, practical code snippets you can directly use

A quick example of a reusable snippet in action:

Quizzes to test concepts in a quick way

Here’s a quick look at how the quiz works:

Here’s a small taste of what the quizzes look like:

1. What does the === operator do?

Checks for value equality only
Checks for reference equality only
Checks for both value and type equality without coercion
Assigns a value

→ Correct answer: Checks for both value and type equality without coercion

2. What is a closure in JavaScript?

A way to immediately end a function
A function that retains access to its outer scope
A syntax error
A loop

→ Correct answer: A function that retains access to its outer scope

3. What will typeof null return?

'null'
'undefined'
'object'
'number'

→ Correct answer: 'object'

A couple of products built from things I personally needed

It’s still growing, still improving, and definitely not perfect.

But it feels closer to what I actually wanted to create.

What Changed for Me

Earlier, I was mostly focused on sharing information.

Now I’m trying to focus more on usefulness.

Instead of just explaining things, I want to:

make it easier to apply them
keep things simple and practical
and help someone save time when they’re stuck

Even the smallest snippet can be helpful if it solves a real problem.

I Missed This Community

One thing I realized during this time is how much I value this space.

Reading posts here, seeing different approaches, and learning from others is something I genuinely enjoy.

I missed that part.

So I’m coming back, not just to share, but also to read, learn, and engage again.

What You’ll See From Me Now

I’ll start sharing more regularly again, but with a slightly different approach.

You’ll see things like:

small useful snippets
short explanations
occasional deep tutorials
and some interesting questions or quizzes

Nothing too heavy. Just practical and helpful.

If You Want to Check What I Built

Here’s how everything comes together:

If you’re curious, you can take a look here:

https://shubhra.dev/

No pressure at all. Just sharing what I’ve been working on.

One Small Thought

Sometimes we feel like we need to keep posting consistently no matter what.

But taking a step back to build something meaningful can be just as important.

For me, this phase helped me rethink what I actually want to create and share.

And I’m glad I took that time.

I’m looking forward to reading your posts again and being more active here.

If you’ve been working on something quietly too, I’d love to hear about it.

DEV Community: Shubhra Pokhariya

My Next.js 16 Optimistic UI Looked Perfect. Then Someone Clicked It Five Times Fast

The fix isn't anything specific to useOptimistic

The rollback question that sent me down a rabbit hole

The cache function question I didn't expect to have opinions about

The error boundary detail that only matters if your error comes from data fetching

Where the rest of this lives

My Next.js 16 Auth Passed Every Test. Five Bugs That Only Showed Up When I Wired It Together.

Bug 1: The Cookie Write That Reported Success and Then Vanished

Bug 2: The Navigation That Never Reached the Proxy

Bug 3: A Database Integer in the JWT Sub Claim

Bug 4: OAuth Sign-In When the Same Email Already Has a Password Account

Bug 5: Forgot Password for an Account That Never Had a Password

What Shipped After These Five Bugs Were Gone

Three Things for the Auth Checklist After This Build

Get the Auth Kit

Next.js 16 Server Actions Security: The Auth Check Most Developers Miss

What "use server" does, and what it does not do

The gap that looks fine until it isn't

The Data Access Layer: why it exists

The Layout trap that catches everyone once

Roles vs permissions inside actions

What to return from Server Actions

Before you ship

Where this series ends

I Got the proxy.ts Matcher Wrong for Three Projects Before I Understood Why

Why the Name Changed

The Runtime Change That Actually Matters for Auth

Migrating From middleware.ts

Building the proxy.ts Auth Gate

Decision 1: The Matcher

Decision 2: The Header Direction

Decision 3: The try/catch

The Header Trust Boundary

Server Functions and the Proxy

Where proxy.ts Sits in the Request Flow

Three Things to Check Before You Ship

I Thought My Next.js 16 Auth Was Solid. One Afternoon Proved Otherwise.

One Thing to Check Before Writing a Line of Auth Code

Why proxy.ts Is Not Your Security Layer (Even Though It Looks Like One)

The Check That Runs Even When Your Proxy Has a Gap

The Backstop That Would Have Caught the Invoice Bug No Matter What

What All Three Layers Look Like on One Request

The Mental Model in One Sentence

After 7 Next.js 16 Caching Bugs, I Stopped Guessing and Built a System

The first problem: tag strings written from memory in different files

The second problem: three different places to invalidate cache, three different correct APIs

The third problem: the PPR split is invisible by default

The fourth problem: cold starts hurt the first visitor after every deploy

What the full system looks like

Next.js 16 Broke My App in 4 Places and None of Them Threw an Error

1. middleware.ts stopped running and told me nothing

2. revalidateTag('products') compiled, deployed, and silently did the wrong thing

3. next lint disappeared and my CI kept saying it passed

4. One component was still reading params synchronously

The pattern that connects all four

7 Next.js 16 Caching Bugs That Compile Fine and Break Silently in Production

Bug 1: 'use cache' on the Wrapper Instead of Inside the Function

Bug 2: Deprecated revalidateTag That Compiles and Uses Legacy Behavior

Bug 3: Tag String Mismatch Across Files

Bug 4: Server Action Mutation Where the Acting User Sees Stale Data

Bug 5: updateTag in a Route Handler

Bug 6: Short cacheLife That Silently Affects PPR

Bug 7: Runtime API Inside a Cached Scope

The Common Thread

I built a free debugger because Next.js 16 'use cache' was completely invisible during development

What it catches

How to use it

Honest limitations

At a glance

Get it

Lighthouse Said It Was Fast. My Users Kept Clicking the Same Button.

The bug wasn’t performance. It was silence.

80ms response, zero perceived response

Where most of us focus (and where it falls short)

The 200ms line

What INP actually measures

The fix was not “make it faster”

The pattern you already use

Why this matters more than Lighthouse 100

1. `middleware.ts` stopped running and told me nothing

2. `revalidateTag('products')` compiled, deployed, and silently did the wrong thing

3. `next lint` disappeared and my CI kept saying it passed

4. One component was still reading `params` synchronously

Bug 1: `'use cache'` on the Wrapper Instead of Inside the Function

Bug 2: Deprecated `revalidateTag` That Compiles and Uses Legacy Behavior

Bug 5: `updateTag` in a Route Handler

Bug 6: Short `cacheLife` That Silently Affects PPR