Confession: I rewrote a perfectly good API route into a server action last summer, broke a Stripe webhook in the process, and didn’t notice for two days. The webhook signature check kept failing because I’d thrown out the raw body somewhere in the conversion. I had to roll the whole thing back, drink a coffee, and write a list of “things I will not do with server actions again.”<\/p>\n
This post is that list. Six mistakes, all real, all stuff I’ve shipped to production at some point and had to clean up. If you’ve already read why I stopped writing API routes for most things<\/a>, this is the other half of that conversation. Server actions are great. They’re also a foot-gun if you treat them like a free abstraction.<\/p>\n Quick context: everything below is for Next.js 15 with the App Router. If you’re on Pages Router, most of this doesn’t apply, and you have my sympathy.<\/p>\n The first time you write a server action, the temptation is to use them for everything. Form submission? Action. Data fetching? Action. Receiving a webhook from Stripe, Clerk, or GitHub? Surely an action.<\/p>\n That last one is wrong. Server actions are not designed to be hit from outside your app. They’re invoked by your own React components via a generated POST endpoint with framework-specific encoding. Stripe doesn’t know about that encoding. Stripe wants a raw JSON body it can verify with Here’s the rule I now follow: if the caller isn’t a React component in this codebase, write a route handler. If the caller is one of my components, write a server action.<\/p>\n The Next.js docs on server actions<\/a> say it plainly: actions are for the client-server roundtrip inside your app. External callers go through Server actions look so much like a regular function call that it’s easy to forget the body crossed the network. I had a project where I validated the form with If you do this, anyone who can hit your site can post arbitrary JSON to your action endpoint with curl. The Zod schema in the client component runs in their browser, not yours. They can simply not run it.<\/p>\n The fix is dull but necessary: validate on the server, every time.<\/p>\n I keep the same Zod schema in a shared file and import it on both sides. Client validates for UX. Server validates for correctness.<\/p>\n You’d think mutating data on the server would, you know, update the UI. It doesn’t, not by itself. The router caches the rendered output of server components, and your action has to tell the router to throw that cache away.<\/p>\n I lost an evening on this with a comments form. The action wrote the comment, the database had it, but refreshing didn’t show the new row. I assumed React was being weird. React was being React. The router cache was stale.<\/p>\n If you tag your fetches, Server actions can throw, but the error that reaches the client is sanitized by default. In production it gets a generic message and a digest. Your nice I shipped that to a customer. They saw the generic message in a toast and assumed the app was broken.<\/p>\n The fix is to return errors as values, not throw them:<\/p>\n1. Reaching for a server action when a route handler was the right call<\/h2>\n
stripe.webhooks.constructEvent<\/code>.<\/p>\n\/\/ Wrong: trying to be clever with a server action\n'use server'\nexport async function handleStripeWebhook(req: Request) {\n \/\/ Stripe has no idea what this signature looks like\n}\n\n\/\/ Right: route handler, raw body preserved\n\/\/ app\/api\/webhooks\/stripe\/route.ts\nexport async function POST(req: Request) {\n const sig = req.headers.get('stripe-signature')!\n const body = await req.text() \/\/ raw, not parsed\n const event = stripe.webhooks.constructEvent(body, sig, secret)\n \/\/ ...\n}\n<\/code><\/pre>\napp\/api\/<\/code>.<\/p>\n2. Trusting the client to validate the form<\/h2>\n
react-hook-form<\/code> plus zod on the client, then passed the parsed object straight into the action. The action wrote it to the database with no further checks.<\/p>\n'use server'\nimport { z } from 'zod'\n\nconst schema = z.object({\n email: z.string().email(),\n plan: z.enum(['free', 'pro']),\n})\n\nexport async function subscribe(formData: FormData) {\n const parsed = schema.safeParse({\n email: formData.get('email'),\n plan: formData.get('plan'),\n })\n if (!parsed.success) {\n return { error: 'Invalid input' }\n }\n \/\/ now you can trust parsed.data\n}\n<\/code><\/pre>\n3. Forgetting revalidatePath and blaming React<\/h2>\n
'use server'\nimport { revalidatePath } from 'next\/cache'\n\nexport async function addComment(postId: string, body: string) {\n await db.comment.create({ data: { postId, body } })\n revalidatePath(`\/posts\/${postId}`) \/\/ tell the router to re-fetch\n}\n<\/code><\/pre>\nrevalidateTag<\/code> does the same thing more surgically. Either way, no revalidation call means stale UI. The Next.js caching docs<\/a> are worth a slow read at least once.<\/p>\n4. Throwing an Error and getting a wall of stack trace in the toast<\/h2>\n
throw new Error('You are not subscribed')<\/code> becomes “An error occurred in the Server Components render.”<\/p>\n'use server'\nexport async function startTrial(userId: string) {\n const user = await db.user.findUnique({ where: { id: userId } })\n if (!user) {\n return { ok: false, error: 'User not found' }\n }\n if (user.trialUsed) {\n return { ok: false, error: 'Trial already used' }\n }\n await db.user.update({ where: { id: userId }, data: { trialUsed: true } })\n return { ok: true }\n}\n<\/code><\/pre>\n