state mismatch 🔐 Authentication

OAuth callback error: state mismatch / Unable to verify authorization request state / State cookie was missing

The state value returned to the callback doesn’t match what the app stored before redirecting — the CSRF protection for OAuth failed.

Seen on: REST API

Meaning

The app stores state (cookie/session) before sending the user to the IdP. If that cookie is lost (SameSite, different domain/port, session store not shared between instances), or the user finishes login in another tab, the check fails.

Common causes

  • State cookie blocked or not sent back (SameSite, secure flag on http)
  • Callback on a different domain/subdomain than where login started
  • Session store not shared across instances
  • Back button / double-submit / multiple tabs

⚡ Quick fix

  1. Start and finish login on the same host (same scheme and port)
  2. Use SameSite=Lax cookies and HTTPS
  3. Use a shared session store (Redis) behind load balancers

Detailed fix by platform

JavaScript

  1. javascript
    // express-session behind a proxy
app.set("trust proxy", 1);
app.use(session({ store: new RedisStore({ client }), cookie: { secure: true, sameSite: "lax" }, resave: false, saveUninitialized: false, secret }));

How to diagnose

  1. Cookie — Present at callback?
  2. Hosts — Same origin?
  3. Instances — Shared sessions?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.