vercel/next.js · error · UnrecognizedActionError

Server Action "${actionId}" was not found on the server. Re

Error message

Server Action "${actionId}" was not found on the server. 
Read more: https://nextjs.org/docs/messages/failed-to-find-server-action

What it means

Thrown as `UnrecognizedActionError` when the server responds to a Server Action POST with the `NEXT_ACTION_NOT_FOUND_HEADER` set to `'1'` (server-action-reducer.ts:174-179). The header means the server's deployed build has no action registered under the `actionId` the client sent. The canonical cause is a client/server build mismatch: the browser holds a stale bundle referencing an action ID that the current server deployment does not export.

Source

Thrown at packages/next/src/client/components/router-reducer/reducers/server-action-reducer.ts:176

        require('../../offline') as typeof import('../../offline')
      if (checkOfflineError(err)) {
        // It's safe to replay the action because the fetch rejection
        // means the request never reached the server — there are no
        // side effects to duplicate.
        const offline = getOffline()
        if (offline !== null) {
          await waitForConnection(offline)
        }
        return fetchServerAction(state, nextUrl, action)
      }
    }
    throw err
  }

  // Handle server actions that the server didn't recognize.
  const unrecognizedActionHeader = res.headers.get(NEXT_ACTION_NOT_FOUND_HEADER)
  if (unrecognizedActionHeader === '1') {
    throw new UnrecognizedActionError(
      `Server Action "${actionId}" was not found on the server. \nRead more: https://nextjs.org/docs/messages/failed-to-find-server-action`
    )
  }

  const redirectHeader = res.headers.get('x-action-redirect')
  const [location, _redirectType] = redirectHeader?.split(';') || []
  let redirectType: RedirectType | undefined
  switch (_redirectType) {
    case 'push':
      redirectType = 'push'
      break
    case 'replace':
      redirectType = 'replace'
      break
    default:
      redirectType = undefined
  }

View on GitHub (pinned to 0ae8c72462)

Solutions

Reload the page (hard refresh) so the browser fetches the current bundle whose action IDs match the server.
Use `unstable_isUnrecognizedActionError` in a Client Component catch block to detect this and prompt the user to refresh, rather than showing a raw error.
Ensure zero-downtime deploys finish before routing traffic to the new build, or drain old instances first.
In dev, restart the dev server and clear `.next` to regenerate manifests.

Example fix

// before
'use client'
await myAction()

// after
'use client'
import { unstable_isUnrecognizedActionError } from 'next/navigation'
try {
  await myAction()
} catch (err) {
  if (unstable_isUnrecognizedActionError(err)) {
    window.location.reload()
    return
  }
  throw err
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Cannot fully prevent — deployment mismatch is server-driven.
// But you can detect build staleness client-side:
// Compare a build-id exposed via __NEXT_DATA__ to the latest on reload.

Type guard

// Client Component only:
import { unstable_isUnrecognizedActionError } from 'next/navigation'
function isUnrecognizedAction(e: unknown): boolean {
  return unstable_isUnrecognizedActionError(e)
}

Try / catch

'use client'
import { unstable_isUnrecognizedActionError } from 'next/navigation'
try {
  await myAction()
} catch (err) {
  if (unstable_isUnrecognizedActionError(err)) {
    // Prompt user to refresh; the client bundle is stale.
    if (confirm('A new version is available. Reload?')) window.location.reload()
    return
  }
  throw err
}

Prevention

Wrap Server Action calls in a helper that catches UnrecognizedActionError and auto-reloads.
Use zero-downtime deploys and drain old instances so clients never hit a mismatched server.
Surface a friendly 'refresh required' UI instead of a raw error for long-lived sessions.

When it happens

Trigger: The browser loaded an older JS bundle whose action reference IDs do not match the server's current `SERVER_REFERENCE_MANIFEST`; a new deployment went out while a user had a tab open; multi-zone setups where the POST is routed to a zone that lacks the action; HMR in dev left a stale reference after the action was renamed/deleted.

Common situations: Long-lived browser sessions across a redeploy; preview deployments where the client cache is stale; renaming or deleting a Server Action without a hard refresh; CDN serving mismatched chunks; load balancer splitting traffic between two versions during a rollout.

Related errors

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/6147fbe16f6566c1. Report an issue: GitHub.