Server Actions fail in three quiet ways, and none of them throws where the bug actually is.
Symptom. Three failures appear after moving a form to Server Actions. The action validates, redirect("/dashboard") runs, the browser stays on the form. Or every upload over a megabyte dies with 413 Request Entity Too Large / Body exceeded 1mb limit. Or useActionState never updates — the action throws, and all the user sees is a generic An error occurred in the Server Components render with a digest instead of your message.
Cause. redirect() and notFound() do not return; they throw a framework-controlled exception that unwinds the render. A try/catch around the call swallows it, and the action completes normally. Separately, Server Actions deserialise their arguments server-side through a body parser with a fixed size limit, and anything thrown inside an action is serialised across the network boundary — an Error instance, a class instance, or a Date in useActionState state cannot make that trip and is replaced with a digest.
Fix. Call redirect() after the try/catch block or rethrow it with isRedirectError/unstable_rethrow; raise serverActions.bodySizeLimit and validate size before upload; and return plain serialisable objects from actions — { ok: false, fieldErrors } — never caught Error objects.
How an action crosses the boundary
An action is a POST to the current route, RSC-encoded, awaited by the client, whose return value must be serialisable through the same encoding. That single sentence explains all three failures.
// app/actions.ts "use server"; import { redirect } from "next/navigation"; export async function createPost(prevState: State, formData: FormData): Promise<State> { const title = String(formData.get("title") ?? ""); try { if (!title) throw new Error("Title is required"); await db.post.create({ data: { title } }); } catch (error) { return { ok: false, message: (error as Error).message }; // never rethrow } redirect("/posts"); // OUTSIDE the try: redirect throws by design } Reproduce the swallowed redirect with the snippet above minus the comment: move redirect() inside try and the form posts, the row is created, and nothing navigates, because the catch block returns a state object instead. The same mistake removes the navigation from notFound() and from unauthorized().
Next.js 15 and 16 ship a size limit of 1 MB per action body. It applies to the whole multipart payload, so a 900 KB image plus form fields can exceed it.
// next.config.ts — Next.js 15+ top-level key; Next 14 used experimental const nextConfig: NextConfig = { serverActions: { bodySizeLimit: "4mb" }, }; // client: check before the request, so the user gets a real message const MAX = 4 * 1024 * 1024; if (file.size > MAX) return { ok: false, message: "File must be under 4 MB" }; A proxy in front of the app has its own limit. Vercel caps request bodies at 4.5 MB for serverless functions, so raising bodySizeLimit past that changes nothing; uploads that large belong in a direct-to-storage signed URL.
Version and boundary reference
| Boundary | What crosses it | Fails when | Fix |
|---|---|---|---|
| Client → action arguments | FormData, serialisable values | File outside FormData, class instances | pass FormData, or a base64 string |
| Action → client return | plain object, string, number, array | Error, Date, Map, class | return { error: string } |
| Action → framework | thrown control-flow errors | caught in try/catch | isRedirectError / unstable_rethrow |
| Body parser | whole multipart payload | over bodySizeLimit | raise limit or upload directly |
| Next.js version | Redirect error helper | Size limit location |
|---|---|---|
| 13.4–13.5 | isRedirectError in next/dist/client/components/redirect | not configurable |
| 14.x | isRedirectError (unstable path) | experimental.serverActions.bodySizeLimit |
| 15.x | unstable_rethrow added | serverActions.bodySizeLimit |
| 16.x | unstable_rethrow stable behaviour | serverActions.bodySizeLimit |
Edge cases and the fixes that work
1. Rethrowing the redirect instead of restructuring
When the redirect genuinely belongs inside the guarded block, the framework's own predicate is the correct escape hatch:
import { isRedirectError } from "next/dist/client/components/redirect-error"; try { await save(formData); redirect("/done"); } catch (error) { if (isRedirectError(error)) throw error; // let the framework unwind return { ok: false, message: "Save failed" }; } That import path is internal and moves between minors. unstable_rethrow(error) from next/navigation is the documented wrapper and covers redirect, not-found, and forbidden in one call.
2. useActionState and non-serialisable state
useActionState keeps the action's return value in React state, which means it is sent through the RSC payload on every update. An Error instance, new Map(), or a Date cannot be encoded and throws Only plain objects, and a few built-ins, can be passed to Client Components from Server Components.
type State = { ok: boolean; message: string; fieldErrors?: Record<string, string> }; export async function updateProfile(_prev: State, formData: FormData): Promise<State> { const parsed = schema.safeParse(Object.fromEntries(formData)); if (!parsed.success) { return { ok: false, message: "Check the form", fieldErrors: parsed.error.flatten().fieldErrors }; } await db.profile.update(parsed.data); return { ok: true, message: "Saved" }; // plain object, no Date } Convert timestamps to ISO strings at the boundary. Error digests exist on purpose: in production an uncaught action error is redacted so an internal stack trace never reaches the browser, which is exactly why a catch that returns error.message must first convert the error into your own string.
3. The 413 that is not the action's limit
Body exceeded 1mb limit comes from the action parser; 413 Request Entity Too Large with no Next.js log line comes from the platform. Check both before changing config:
# platform limit, not framework limit curl -s -o /dev/null -w "%{http_code}\n" -X POST https://app.example.com/api/upload \ -F "file=@big.zip" If the plain route returns 413 while a small action works, the reverse proxy is the limit. For Vercel, request.body above 4.5 MB cannot be raised by configuration at all.
4. revalidatePath order relative to the redirect
Data cache invalidation belongs before the redirect, because the redirect ends the action.
await db.post.update({ where: { id }, data }); revalidatePath("/posts"); revalidateTag("posts"); redirect(`/posts/${id}`); // last statement, never followed by more work redirect() returning a typed never means code after it is unreachable and tsc will flag it. That is a feature: use it to prove the action cannot continue after navigation.
5. Actions called outside a form
<form action={}> passes FormData automatically; a startTransition call does not. Passing an object works, but passing a File directly does not — only FormData carries binary through the action encoding.
"use client"; const [isPending, startTransition] = useTransition(); <button onClick={() => startTransition(() => publish(post.id))} disabled={isPending}> Publish </button> 6. Error boundaries do not catch action errors in production
An error.tsx boundary catches render errors, and an uncaught action error arrives as a redacted digest that error.tsx never sees unless the client rethrows it. Handle expected failure inside the action and return state; reserve throwing for genuinely broken invariants, where a digest and a server log are the right outcome.
Common mistakes and version gotchas
-
redirect()insidetry/catch— swallowed. Move it out or rethrow withunstable_rethrow. -
redirect()in asetTimeoutor afterawaitpast the response — the action has returned, so the navigation is lost. - Returning
Errorfrom an action — not serialisable; return a string or a plain object. -
useActionStateaction that does not take(prevState, formData)— React passes the previous state as the first argument and the signature mismatch shows asformData.get is not a function. -
bodySizeLimitunderexperimentalon Next.js 15+ — ignored, and the 1 MB default stays. -
revalidatePathafterredirect— unreachable; invalidate first. - Actions used as event handlers directly —
onClick={myAction}posts nothing; wrap instartTransitionor use a form.
Related tools. Paste a failed payload and inspect it with the JSON formatter, test a multipart request without the app in the way using cURL to code, and compare the action's serialised state between the versions in a text diff.
