Three bugs, one session: fixing a NextAuth v5 race condition, Next.js 16 async params, and broken contest URLs

A user submits their username handle. The API saves it to the database. The button disables. And then nothing happens. The form just sits there — no error, no redirect, no way to click anything. The only way out is a hard browser refresh, which dumps you back on the same page. Three separate bugs, diagnosed in a single session, all from reading network responses rather than logs.

Bug one: NextAuth v5 session.update() does not touch the JWT cookie

The onboarding page called session.update() from useSession() after a successful API response, then navigated to the homepage. The intent was clear: tell NextAuth the username is now set, then redirect. The middleware guard checks session.user.username — if it is null, redirect back to onboarding. The assumption was that update() would refresh the JWT cookie so the middleware would see the new value.

That assumption is wrong. NextAuth v5 update() is a client-side only operation. It updates the in-memory session object that React components read via useSession(). It makes no HTTP request. It writes nothing to the server. The HTTP-only JWT cookie — the thing middleware reads — is completely unchanged.

So when window.location.href fired and the browser hit the homepage, middleware called auth(), read the JWT cookie, found username: null, and redirected straight back to /onboarding/username. The user never left. The form appeared to reset. The button sat there disabled. Infinite loop, invisible to the user as anything other than the page not working.

The JWT callback already had the fix built in

The auth.ts jwt callback has three conditions that trigger a database re-fetch. The third one is the key:

// auth.ts
async jwt({ token, user, trigger }) {
  if (
    user?.email ||           // initial sign-in
    trigger === "update" ||  // explicit client-side update()
    (token.dbId && token.username === null)  // ← fires on every request when username not yet set
  ) {
    const { data } = await supabase
      .from("users")
      .select("id, role, username")
      .eq("id", token.dbId)
      .single();
    token.username = data?.username ?? null;
  }
  return token;
}

The third condition — token.dbId exists but token.username is null — was designed exactly for this scenario. It fires on every incoming request while a user is signed in but has not completed onboarding. This means the fix required no changes to the JWT callback at all. The mechanism was already there.

// Before — onboarding/username/page.tsx
import { useSession } from "next-auth/react";

const { update } = useSession();

if (res.ok) {
  await update({ username }); // updates client cache only, not the cookie
  window.location.href = "/"; // middleware sees stale JWT, redirects back
}

// After
if (res.ok) {
  // jwt callback's token.username === null guard re-fetches from DB on next request
  window.location.replace("/"); // replace() also removes onboarding from browser history
}

Bug two: Next.js 16 made params a Promise and one route missed the migration

In Next.js 15, params and searchParams in Server Components became asynchronous — they return a Promise, not a plain object. Every dynamic route in this project had already been updated to the new pattern except one: app/archive/[week]/page.tsx. Accessing params.week synchronously in Next.js 16 throws a runtime error that the nearest error boundary catches silently.

// Before — app/archive/[week]/page.tsx
type Props = { params: { week: string } };

export async function generateMetadata({ params }: Props) {
  const week = params.week; // throws in Next.js 16
}

export default async function ArchiveWeekPage({ params }: Props) {
  const week = parseInt(params.week, 10); // throws in Next.js 16
}

// After
type Props = { params: Promise<{ week: string }> };

export async function generateMetadata({ params }: Props) {
  const { week } = await params;
}

export default async function ArchiveWeekPage({ params }: Props) {
  const { week: weekStr } = await params;
  const week = parseInt(weekStr, 10);
}

The fix is mechanical — update the type signature and await the params object. The reason for destructuring to weekStr in the page function rather than directly to week is that parseInt produces a number, and having two consts named week in the same scope (the string from params and the parsed integer) would require one to shadow the other. weekStr makes the types explicit.

Bug three: the correct URL was computed but never used

The archive page links to past contests. Both an ai_art contest and a photo contest were archived. The archive cards were linking to /archive/1 and /archive/2 — the contest number — instead of /contests/photo/{uuid} or /contests/ai-art/{uuid}. The same bug appeared in the LastWinner component on the homepage.

// ArchiveCard.tsx — before
<Link href={`/archive/${contest.contest_number}`}>

// ArchiveCard.tsx — after
const contestPath = contest.contest_type === "photo"
  ? `/contests/photo/${contest.id}`
  : `/contests/ai-art/${contest.id}`;

<Link href={contestPath}>

// LastWinner.tsx — before
const typePath = contestType === "photo" ? "photo" : "ai-art"; // computed, never used
<Link href={`/archive/${contestNumber}`}>

// LastWinner.tsx — after
const typePath = contestType === "photo" ? "photo" : "ai-art";
const contestPath = `/contests/${typePath}/${artwork.contest_id}`;
<Link href={contestPath}>

The archive page query also did not include contest_type in the select, so ArchiveCard had no way to build the correct URL even after the href was fixed. That required adding contest_type to the Supabase select alongside the existing id field.

Diagnosed entirely from a network response, no logs required

None of these bugs produced Sentry events or Vercel function logs. The archive page bug in particular looked like a hanging Suspense boundary — the loading skeleton rendered but the page content never streamed in. The diagnosis came from opening the Network tab, clicking the /archive/1 request, and reading the raw RSC payload in the Response tab.

The payload showed the archive listing page metadata — title: Archive, canonical: /archive — rendering at the /archive/1 URL. The [week] page generateMetadata had never run. That proved the page component was throwing before it could produce output, not hanging. The async params fix resolved it. The ISR cache theory (that a stale error response was being served) turned out to be a red herring — the wrong URL in ArchiveCard was the actual problem, and the [week] page crash was a separate bug that happened to coexist.

The pattern all three bugs share

Each bug was a gap between what the code appeared to do and what it actually did. session.update() looked like it updated the session — it updated a cache. params.week looked like a string property — it was a Promise. typePath looked like it was being used in the href — it was declared and ignored. None of these required deep debugging tools. They required reading the mechanism, not just the symptom. That is the core of Directed Output: before reaching for a workaround, understand what the thing you are calling actually does.

From the build log