Passport 0.6 deserializeUser error handling divergence between done(err) and done(null, false)

Answer

In Passport 0.6 the deserializeUser callback must be used to distinguish two fundamentally different situations:

• Operational failure – a problem that prevents the user lookup (e.g., database down). Use done(err) so the error propagates via next(err) to Express’s error handler.
• Missing user record – the session contains a valid identifier, but the corresponding user no longer exists in the database. Use done(null, false) so req.user becomes false and the request is treated as unauthenticated.

Calling done(null, undefined) behaves like done(null, false) in 0.6, but explicit false is clearer for downstream checks.

Interaction with authenticate’s next(err)

Prior to 0.6, strategy errors inside deserializeUser were thrown and caught by local try/catch wrappers around authenticate. 0.6 replaces that with next(err), so:

• An err passed to done is forwarded to Express’s error middleware. Your global error handler can then decide whether to return a 500 or a custom status.
• A null, false result bypasses error middleware; req.user becomes false and any route that requires authentication will typically respond with 401 or 403.

Migrating Sessions Across Passport Releases

Because Passport stores only the serialized user ID, a change in deserializeUser can silently alter req.user for all existing sessions. The safest pattern is:

1. Introduce a sessionVersion field on the user model (or a dedicated session store column).
2. When upgrading, bump the expected version number in your deserializeUser implementation.
3. During deserialization, compare the stored version with the expected one. If they differ, treat the session as stale: call done(null, false) to force re‑authentication.
4. Optionally, clear the session cookie on the client side when a mismatch occurs to avoid a looping redirect.
5. Keep the old session data in the database but mark it as obsolete; you can later clean it up in a background job.

If you cannot add a version field, the fallback is to invalidate all sessions by rotating the session secret or clearing the session store entirely. This guarantees that no session will be misinterpreted under the new deserializeUser contract.

What to Verify Now

To ensure the chosen pattern works, run a quick test:

passport.deserializeUser((id, done) => {
  User.findById(id, (err, user) => {
    if (err) return done(err);          // triggers next(err)
    if (!user) return done(null, false); // req.user === false
    done(null, user);
  });
});

After deployment, monitor the Express error middleware for unexpected 500 responses and confirm that unauthenticated routes receive 401/403 when req.user is false.

Missing Diagnostic Detail

Do you currently store a sessionVersion or equivalent version marker in your session or user records? Knowing this will help refine the migration strategy.