I spent most of a Thursday convinced I’d found a Next.js bug. I hadn’t. I’d found a paragraph in the docs that I had somehow never read, in a guide I would have sworn I’d read twice.<\/p>\n
The setup was boring. A settings page with three toggles: dark mode, timezone, weekly digest. Each one saved independently. I wrapped the three saves in a I blamed my database. I blamed the dev server. I restarted things. Eventually I read the Server Actions guide<\/a> properly and found the sentence that explains it, sitting right there under a heading called “Sequential dispatch on the client.”<\/p>\n So here are the two rules I wish I’d internalised a year ago. Neither is exotic. Both cost me real hours.<\/p>\n Next.js dispatches Server Actions one at a time from a given client. Trigger three in quick succession and the second waits for the first, the third waits for the second. This isn’t a quirk of my code, it’s the client dispatcher doing it on purpose so the re-rendered server tree stays consistent with whichever action result produced it.<\/p>\n That’s a reasonable trade. It also means this is a lie:<\/p>\n The fix is to stop treating actions like RPC endpoints and start treating them like transactions. One action, one mutation, one re-render:<\/p>\n If you genuinely need parallel work, do it inside a single action, or fetch in parallel from a Server Component, or use a Route Handler for anything that isn’t a mutation. The docs say all three of those things. I just hadn’t looked.<\/p>\n The thing I keep having to say out loud to myself: a Server Action is a React Server Function<\/a> wired into React’s action mechanism. It isn’t a fetch call with nicer syntax. The queuing is the price of getting fresh UI back in the same response.<\/p>\n I think the sequential thing only surprises people who came to actions from the API route era, which is most of us. It’s worth putting the two side by side, because the “after” is genuinely smaller and that’s the part that sold me.<\/p>\n The old way. A route handler, plus a client component doing optimistic state by hand, plus a rollback you wrote at 11pm and never tested:<\/p>\n Plus the handler itself, which is where the auth check lives:<\/p>\n Two files, a serialisation round trip, and client state that can drift from server state whenever the request fails in a way you didn’t anticipate.<\/p>\n The new way, using the action above:<\/p>\n No local mirror of server state. No manual rollback. The action mutates, invalidates, and Next.js re-renders the route server side, shipping the new RSC payload back in the same response. For forms specifically I’d reach for This is the one that actually shipped a bug for me, rather than just wasting an afternoon.<\/p>\n There are four ways to update things after a mutation and they behave differently:<\/p>\n My bug: user toggles the weekly digest, action calls Related, and worth knowing before you upgrade: You can pass a built-in profile like While you’re in there: A Server Action is a POST endpoint. The Next.js does give you an Origin\/Host CSRF check, a 1MB body limit by default, encrypted action IDs, and closure variable encryption. Useful. Not a substitute for checking who’s calling.<\/p>\n The failure mode I’ve written more than once: accepting the whole object from the client.<\/p>\n Zod would happily validate the unsafe version. Schema validation checks shape, not ownership. A perfectly well formed object can still point at a row that isn’t yours.<\/p>\n If you’re self hosting across multiple instances, set Grep your codebase for Then grep for Both greps took me under ten minutes. The second one found two more instances of the bug I’d already fixed once.<\/p>\n","protected":false},"excerpt":{"rendered":" Server Actions in Next.js 16 queue one at a time, and revalidateTag no longer means what it used to. The two rules that cost me a Thursday, with code.<\/p>\n","protected":false},"author":2,"featured_media":526,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"","rank_math_description":"Server Actions in Next.js 16 queue one at a time, and revalidateTag no longer means what it used to. The two rules that cost me a Thursday, with code.","rank_math_focus_keyword":"nextjs server actions","rank_math_canonical_url":"","rank_math_robots":"","footnotes":""},"categories":[35],"tags":[353,61,41,62,39],"class_list":["post-527","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-web-development","tag-caching","tag-nextjs","tag-react","tag-server-actions","tag-web-development"],"_links":{"self":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/527","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/comments?post=527"}],"version-history":[{"count":0,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/527\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media\/526"}],"wp:attachment":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media?parent=527"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/categories?post=527"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/tags?post=527"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}Promise.all<\/code> because that’s what you do when you have three independent async things, and then I sat there watching the network tab show them go one, then the next, then the next. Neatly queued. Politely waiting their turn. Total time roughly the sum of all three.<\/p>\nRule one: server actions queue, one at a time, per client<\/h2>\n
\/\/ Looks parallel. Is not parallel.\nawait Promise.all([\n saveTheme('dark'),\n saveTimezone('Asia\/Dubai'),\n saveDigest(true),\n])\n<\/code><\/pre>\n\/\/ app\/settings\/actions.ts\n'use server'\n\nimport { updateTag } from 'next\/cache'\nimport { auth } from '@\/lib\/auth'\nimport { db } from '@\/lib\/db'\n\nexport async function saveSettings(patch: SettingsPatch) {\n const session = await auth()\n if (!session?.user) throw new Error('Unauthorized')\n\n await db.settings.update({\n where: { userId: session.user.id },\n data: patch,\n })\n\n updateTag(`settings-${session.user.id}`)\n}\n<\/code><\/pre>\nWhat this replaced, in actual code<\/h2>\n
\/\/ app\/settings\/notification-toggle.tsx\n'use client'\nimport { useState } from 'react'\n\nexport function NotificationToggle({ initial }: { initial: boolean }) {\n const [on, setOn] = useState(initial)\n const [saving, setSaving] = useState(false)\n\n async function toggle() {\n setSaving(true)\n setOn(!on)\n const res = await fetch('\/api\/settings\/notifications', {\n method: 'POST',\n headers: { 'Content-Type': 'application\/json' },\n body: JSON.stringify({ enabled: !on }),\n })\n if (!res.ok) setOn(on) \/\/ roll back and hope\n setSaving(false)\n }\n\n return (\n <button onClick={toggle} disabled={saving}>\n {on ? 'On' : 'Off'}\n <\/button>\n )\n}\n<\/code><\/pre>\n\/\/ app\/api\/settings\/notifications\/route.ts\nexport async function POST(req: Request) {\n const session = await auth()\n if (!session?.user) return new Response('Unauthorized', { status: 401 })\n\n const { enabled } = await req.json()\n await db.settings.update({\n where: { userId: session.user.id },\n data: { notifications: enabled },\n })\n return Response.json({ ok: true })\n}\n<\/code><\/pre>\n'use client'\nimport { useTransition } from 'react'\nimport { saveSettings } from '.\/actions'\n\nexport function NotificationToggle({ on }: { on: boolean }) {\n const [pending, startTransition] = useTransition()\n\n return (\n <button\n disabled={pending}\n onClick={() => startTransition(() => saveSettings({ notifications: !on }))}\n >\n {on ? 'On' : 'Off'}\n <\/button>\n )\n}\n<\/code><\/pre>\nuseActionState<\/code> instead of useTransition<\/code>, which I wrote about in the post about deleting form boilerplate<\/a>.<\/p>\nRule two: the cache call you pick decides whether the user sees their own change<\/h2>\n
updateTag<\/code> expires a tag immediately. The route re-render that rides along with the action’s response waits for the fresh data. This is what you want when a user changes their own settings and expects to see them.<\/p>\nrevalidateTag<\/code> marks a tag stale and refreshes in the background. The action’s own re-render does not wait. Fine for a blog index. Wrong for a settings page, which is exactly what I shipped.<\/p>\nrevalidatePath<\/code> invalidates by URL path. Useful when one route is affected and tagging is more machinery than the problem deserves. Worth reading the path caveats<\/a> if you use rewrites, because you have to pass the destination path, not the one in the address bar.<\/p>\nrefresh<\/code> refetches the current route’s RSC payload without invalidating any cached data. For when the view depends on something outside the cache.<\/p>\nrevalidateTag<\/code>, response comes back, toggle flips back to its old value for a second, then corrects itself. Users reported it as “the setting doesn’t save.” It saved fine. The UI was just reading the stale value that stale-while-revalidate is designed to hand you. Swapping in updateTag<\/code> fixed it in one line.<\/p>\nrevalidateTag grew a second argument in 16<\/h2>\n
revalidateTag<\/code> now requires a cache life profile as its second argument. The single-argument form is deprecated and will give you a TypeScript error.<\/p>\n\/\/ Next.js 15\nrevalidateTag('posts')\n\n\/\/ Next.js 16\nrevalidateTag('posts', 'max')\n<\/code><\/pre>\nmax<\/code>, hours<\/code> or days<\/code>, or an inline custom one. The version 16 upgrade guide<\/a> covers this alongside the other breaking changes, and the codemod handles most of the mechanical ones. It does not decide for you whether a given call site wanted updateTag<\/code> instead. That’s the judgement call, and it’s the one worth making by hand.<\/p>\nmiddleware<\/code> is now proxy<\/code>, Turbopack is the default for both dev and build, and synchronous cookies()<\/code> and params<\/code> access is fully gone rather than merely deprecated. I went through the App Router migration on this blog last year and wrote up what actually broke<\/a>, most of which was cache assumptions rather than routing.<\/p>\nThe bit I still catch myself skipping<\/h2>\n
'use server'<\/code> directive swaps the implementation out of your client bundle and leaves behind an encrypted action ID that POSTs back. The implementation stays on the server, which is good, but the route is reachable by anyone who can send that POST.<\/p>\n'use server'\n\n\/\/ Unsafe. The id comes from the client, so anyone who can POST here\n\/\/ can mark any row complete.\nexport async function completeItemUnsafe(item: Item) {\n await db.item.update({ where: { id: item.id }, data: { completed: true } })\n}\n\n\/\/ Safe. Take the change, derive identity from the session, look up by ownership.\nexport async function completeItem(itemId: string) {\n const session = await auth()\n if (!session?.user) return\n\n const item = await db.item.findFirst({\n where: { id: itemId, ownerId: session.user.id },\n })\n if (!item) return\n\n await db.item.update({ where: { id: item.id }, data: { completed: true } })\n}\n<\/code><\/pre>\nNEXT_SERVER_ACTIONS_ENCRYPTION_KEY<\/code> to a stable value shared across them, otherwise closure decryption fails on whichever instance didn’t build the bundle. I’ve done deployment plumbing like this for a few client projects and it’s usually the last thing anyone thinks of, so I’ve started putting it in the setup notes I keep for these builds<\/a>.<\/p>\nWhat I’d do this week<\/h2>\n
Promise.all<\/code> anywhere near an imported server action. If you find one, you have a serialised queue pretending to be parallel, and the fix is usually to merge those actions into one.<\/p>\nrevalidateTag<\/code>. For each call site, ask one question: does the person who just clicked need to see this change immediately? If yes, it should be updateTag<\/code>. If it’s a blog index or a product catalogue where a few seconds of stale is fine, leave it, but add the cache life profile before you upgrade to 16 or the build will complain.<\/p>\n