nextauthjs/next-auth · error · UnknownAction

Cannot handle action: ${action}

Error message

Cannot handle action: ${action}

What it means

AuthInternal's action router throws UnknownAction when the requested action does not match any case in its switch (session, signout, etc.). It means the URL was parsed to an action string the core runtime cannot dispatch. This is the terminal guard after the switch statement in the auth internal handler.

Source

Thrown at packages/core/src/lib/index.ts:96

        validateCSRF(action, csrfTokenVerified)
        return await actions.session(
          options,
          sessionStore,
          cookies,
          true,
          request.body?.data
        )
      case "signin":
        validateCSRF(action, csrfTokenVerified)
        return await actions.signIn(request, cookies, options)

      case "signout":
        validateCSRF(action, csrfTokenVerified)
        return await actions.signOut(cookies, sessionStore, options)
      default:
    }
  }
  throw new UnknownAction(`Cannot handle action: ${action}`)
}

View on GitHub (pinned to a1a16a5a77)

Solutions

1. Align the versions of @auth/core and your framework adapter (upgrade or downgrade together)
2. Check the exact URL path being requested and only use documented auth endpoints (signin, signout, callback, session, csrf, providers, error)
3. If behind a custom proxy, ensure it forwards the original pathname unmodified

Example fix

// before
auth: import { Auth } from "@auth/core" // 0.10.0 with next-auth@5.0.0-beta.4
// after
pnpm up @auth/core@latest next-auth@latest  # keep them on compatible versions

const KNOWN_ACTIONS = ["signin","signout","callback","session","csrf","providers","error","webauthn-options"];
if (!KNOWN_ACTIONS.includes(action)) throw new Error(`Skip request, unsupported action: ${action}`);

function isKnownAuthAction(a: string): a is "signin"|"signout"|"callback"|"session"|"csrf"|"providers"|"error"|"webauthn-options" { return ["signin","signout","callback","session","csrf","providers","error","webauthn-options"].includes(a); }

try { await handleAuth(req) } catch (e) { if (e instanceof UnknownAction) return new Response("Not Found", { status: 404 }); throw e; }

When it happens

Trigger: Calling an endpoint like /auth/<action> whose action passed isAuthAction() parsing but has no switch case handled by the installed AuthInternal version (e.g. an action added in a newer @auth/core than the framework adapter, or an unmatched case after CSRF/session branches fall through).

Common situations: Version mismatch between the framework adapter (next-auth, sveltekit-auth) and @auth/core; typos in custom proxy/routing that pass an unexpected action string; calling endpoints like /auth/diagnostics that only exist in some builds.

Related errors

• [updateSession] Failed to fetch updated session
• Object is nullish
• User not found
• Account not found
• Session not found

AI-assisted analysis of nextauthjs/next-auth@a1a16a5a77 (2026-08-28). Data as JSON: /api/errors/6eb21b2e9618d3f5. Report an issue: GitHub.