Fix "Failed to find Server Action" after a Next.js deploy: build key, route handler, recovery

Someone has your page open from before a deploy, submits a form, and Next.js answers 409 with "Failed to find Server Action" because the new build gave every action a new id. This page is the code side: pin NEXT_SERVER_ACTIONS_ENCRYPTION_KEY at build time in Docker, a script that proves two builds share their ids, a sign-in route handler with no id to go stale, and an error boundary that reloads once instead of a dead screen.

One payment$3

By buying you agree to the Terms.

One payment, no subscription
Download right after paying
Use it in client projects
Won't run on the listed stack? We fix it or refund you

Ready forCursorv0Lovableshadcn CLI

Full product pageReact · Tailwind · TypeScript

Fix 1: pin the key when next build runs

Dockerfile

FROM node:22-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
# Every Server Action id is derived from this key when next build runs.
# A build secret keeps it out of the image layers and the build log.
RUN --mount=type=secret,id=next_sa_key \
    NEXT_SERVER_ACTIONS_ENCRYPTION_KEY="$(cat /run/secrets/next_sa_key)" npm run build

FROM node:22-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/.next ./.next
COPY --from=build /app/public ./public
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/package.json ./package.json
CMD ["npm", "start"]

# build it with:
#   docker build --secret id=next_sa_key,env=NEXT_SERVER_ACTIONS_ENCRYPTION_KEY -t app .

scripts/action-ids.mjs

// scripts/action-ids.mjs: print the Server Action ids of the last next build,
// one per line. It never prints the key itself.
// Build the same commit twice and diff the two lists: with the key pinned they match.
import { readFileSync } from "node:fs";

const manifest = JSON.parse(readFileSync(".next/server/server-reference-manifest.json", "utf8"));
const ids = [...Object.keys(manifest.node ?? {}), ...Object.keys(manifest.edge ?? {})].sort();
console.log(ids.join("\n"));

Good to know

The key has to exist when next build runs. The ids are written into the build output, so setting the variable only at runtime changes nothing. In Coolify, tick it as a build variable; on other hosts, check that build steps see it.
Generate it once with openssl rand -base64 32 and keep it as a secret. It also encrypts the values Server Actions close over, so it never belongs in the repo or in a chat.
Renaming an action or moving it to another file still gives it a new id, key or no key. Editing what the function does keeps the id.
On Vercel, Skew Protection keeps old pages talking to the deployment they came from, which covers the same problem from the hosting side.
What we ran on October 27, 2026: the route handler, the sign-in helper and the error boundary type-check with TypeScript 5.9.3 against react 19.1.1 and next 15.5.28, in strict mode, and action-ids.mjs ran in Node against a real next build manifest. We didn't build this Dockerfile or trigger the error boundary on this page; the key behaviour itself (same ids across clean builds, the 409 without it) was measured for our blog post on Next.js 16.4.2.

Fix 2: post the sign-in form to a route handler

A route handler has a fixed URL, so a page from an older build still posts to something that exists. For login, sign-up and checkout, the forms you can least afford to break, this removes the problem instead of managing it.
The handler answers JSON to fetch and a 303 redirect to a plain form post, so it also works with JavaScript off. The same-origin check stands in for the CSRF protection Server Actions give you for free.

app/api/sign-in/route.ts

import { cookies } from "next/headers";

// A route handler lives at a fixed URL, so a page left open across a deploy
// still posts to something that exists. No action id to go stale.
function sameOrigin(request: Request) {
  const origin = request.headers.get("origin");
  const host = request.headers.get("x-forwarded-host") ?? request.headers.get("host");
  return origin !== null && host !== null && new URL(origin).host === host;
}

export async function POST(request: Request) {
  if (!sameOrigin(request)) return new Response("Forbidden", { status: 403 });
  const form = await request.formData();
  const email = String(form.get("email") ?? "").trim();
  const password = String(form.get("password") ?? "");
  const wantsJson = request.headers.get("accept")?.includes("application/json") ?? false;

  const session = await verify(email, password);
  if (!session) {
    return wantsJson
      ? Response.json({ message: "Wrong email or password." }, { status: 401 })
      : new Response(null, { status: 303, headers: { Location: "/login?error=1" } });
  }

  (await cookies()).set("session", session, { httpOnly: true, secure: true, sameSite: "lax", path: "/" });
  return wantsJson ? Response.json({ ok: true }) : new Response(null, { status: 303, headers: { Location: "/dashboard" } });
}

async function verify(email: string, password: string): Promise<string | null> {
  // your auth here: Supabase, Auth.js, Clerk's backend API or your own users table
  void email;
  void password;
  return null;
}

lib/sign-in.ts

// What the login form's submit handler calls. It throws on a wrong password,
// so the form can show the message and shake.
export async function signIn(email: string, password: string): Promise<void> {
  const body = new FormData();
  body.set("email", email);
  body.set("password", password);
  const res = await fetch("/api/sign-in", { method: "POST", headers: { Accept: "application/json" }, body });
  if (!res.ok) {
    const data: { message?: string } = await res.json().catch(() => ({}));
    throw new Error(data.message ?? "Sign in failed. Try again.");
  }
  window.location.assign("/dashboard");
}

Fix 3: reload once instead of the error screen

Without a boundary, the visitor gets Next's built-in error page and loses what they typed. app/error.tsx can spot the stale-action message and reload once, which loads the new build's ids. The sessionStorage flag stops a reload loop if something else is wrong.

app/error.tsx

"use client";
import { useEffect } from "react";

const STALE = /Server Action .* was not found|Failed to find Server Action/i;

// A page from the old build posted an action id the new build doesn't know.
// Reload once to pick up the new ids instead of leaving a dead error screen.
export default function ErrorPage({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
  const stale = STALE.test(error.message);

  useEffect(() => {
    if (!stale || sessionStorage.getItem("qd-reloaded")) return;
    sessionStorage.setItem("qd-reloaded", "1");
    window.location.reload();
  }, [stale]);

  useEffect(() => {
    const id = setTimeout(() => sessionStorage.removeItem("qd-reloaded"), 10_000);
    return () => clearTimeout(id);
  }, []);

  return (
    <main className="mx-auto max-w-md p-6 text-center">
      <p className="text-zinc-300">{stale ? "We just updated the site. Loading the new version..." : "Something went wrong."}</p>
      {!stale && (
        <button type="button" onClick={reset} className="mt-4 rounded-lg bg-lime-400 px-4 py-2 text-zinc-950">
          Try again
        </button>
      )}
    </main>
  );
}

Pull-Cord Login is the sign-in card where pulling a lamp cord turns the light on and the form appears. Its onSubmit takes any function that returns a promise, so you pass it the signIn helper from Fix 2 and the form posts to the route handler: no Server Action id, nothing to break on the next deploy.
Want the free pieces first? The free kit is MIT.

The free kit: Toast Stack, Pricing Switch, Upload Dropzone and more, MIT

Install

Copy from the zipPut react/src/components into src/, then none. Next.js App Router; Docker BuildKit for the build secret.
Or ask your AIPaste PROMPT.md into Cursor, Lovable or v0.

Props

onSubmit: valid credentials, return a promise
defaultOn: start with the light on
onToggle: every pull
accent: bead and button colour

How qodesign compares

qodesign vs Magic UIMagic UI is best for: landing pages built with shadcn/ui.
qodesign vs Aceternity UIAceternity UI is best for: teams building many marketing pages who want one big library.

All comparisons, with prices read on each library's own site.

From the blog: Fix "Failed to find Server Action" in Next.js After a Deploy

From the blog: Toast Notifications After a Next.js Server Action (Sonner, useActionState, redirect)

Questions

What does "Failed to find Server Action" mean?

The page sent an action id from one build to a server running another build. Without a pinned key, every next build gives every action a new id.

Does NEXT_SERVER_ACTIONS_ENCRYPTION_KEY need to be set at runtime?

It has to be there when next build runs. The ids are baked into the build output, so a runtime-only variable does nothing.

Should I use a route handler instead of a Server Action for forms?

For login, sign-up and checkout, yes: a fixed URL can't go stale across deploys. Server Actions are fine for forms where a reload costs nothing.

Does renaming a Server Action break open pages?

Yes. A new name or a new file is a new action, even with the key pinned.

Does the form work in Next.js?

Yes, as a client component. Keep "use client" at the top of the file that renders it, as in the snippet above. App Router and Pages Router both work.

Can Cursor or v0 add it for me?

Yes. Each download has a PROMPT.md. Paste it into Cursor, Lovable, v0 or Claude Code and it fits the piece into your app.

Can I use it in client work?

Yes, in personal and client projects. You can't resell the code itself as a kit.

Fix "Failed to find Server Action" after a Next.js deploy: build key, route handler, recovery

Fix 1: pin the key when next build runs

Good to know

Fix 2: post the sign-in form to a route handler

Fix 3: reload once instead of the error screen

Where Pull-Cord Login fits

Install

Props

How qodesign compares

Questions

Fix 1: pin the key when next build runs

Good to know

Fix 2: post the sign-in form to a route handler

Fix 3: reload once instead of the error screen

Where Pull-Cord Login fits

Install

Props

How qodesign compares

Questions