express-session

Postconditions — what we check

• session · missing-secret

  error
  Whensession() is called without a secret option
  ThrowsTypeError: secret option required for sessions
  Required handlingCaller MUST provide a secret string or array of strings. This is a startup-time configuration error — the middleware will throw synchronously and the Express app will fail to start.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• session · store-error

  error
  WhenThe session store emits an error (e.g., Redis connection failure, store.get/set/destroy fails)
  ThrowsError — forwarded to Express error handler via next(err)
  Required handlingApplication MUST register an Express error handler (4-argument middleware) to handle store errors. Without it, store failures will cause unhandled errors or 500 responses. Consider using store's reconnect/retry logic to handle transient failures.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• session · session-not-saved-without-changes

  info
  WhenSession data is not modified during the request and saveUninitialized: false is set
  ReturnsSession is not saved to the store. No Set-Cookie header is sent.
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• session · success

  info
  WhenSession middleware initializes or resumes a session successfully
  Returnsreq.session is populated with session data. req.session.id and req.session.cookie are set.
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• req.session.destroy · destroy-callback-error-unchecked

  warning
  Whenreq.session.destroy(callback) called but callback does not check the err argument. Store errors from Redis disconnect, PostgreSQL connection loss, or any persistent store failure are silently swallowed.
  ThrowsStore-dependent errors passed as first argument to callback: Redis: ReplyError (READONLY, WRONGTYPE, connection lost) PostgreSQL: Error from pg (connection terminated, relation does not exist) Generic: Error('could not destroy session') from custom stores
  Required handlingCaller MUST check err in the destroy callback. The pattern: req.session.destroy(function(err) { if (err) { /* handle */ } ... }) Without checking err: store failures are silently ignored, the session may persist in the store (user not actually logged out from server side), and monitoring systems never see the failure. The session cookie is cleared on the client regardless — creating a split-brain where the client thinks the session is gone but the store still has it.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[2][3]
• req.session.destroy · destroy-no-callback

  error
  Whenreq.session.destroy() called without any callback. Store errors have no handler at all. The destroy operation is fire-and-forget with no way to react to failure.
  ReturnsNo value returned that indicates success or failure. Store errors are silently swallowed. In Node.js environments without a global uncaughtException handler, unhandled errors in store callbacks may go completely unnoticed.
  Required handlingAlways pass a callback to req.session.destroy(). Even a minimal error logger is better than no callback. In redirect-after-logout flows, the redirect MUST happen inside the callback — not after it — to ensure the session is actually destroyed before the user is redirected.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[2][3]
• req.session.regenerate · regenerate-callback-error-unchecked

  error
  Whenreq.session.regenerate(callback) called but callback does not check err. If the store fails to destroy the old session, the error is silently ignored. The new session is still created (store.generate() always runs regardless of err in the destroy step), but the old session may persist in the store.
  ThrowsStore-dependent errors passed as first argument to callback: Same error types as destroy: Redis ReplyError, PostgreSQL connection errors. Error from store.destroy() when the old session cannot be removed.
  Required handlingCaller MUST check err in the regenerate callback. If err is present after login, the regeneration failed and the session fixation defense may be incomplete. Minimum required: if (err) { return next(err); } // abort login, don't proceed with authenticated state Never call next() or redirect without checking err — doing so can leave the user authenticated on a compromised session ID.
  costhighin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[2][4]
• req.session.save · save-callback-error-unchecked

  error
  Whenreq.session.save(callback) called explicitly (e.g., before redirect) but callback does not check err. If the session store fails (Redis timeout, DB write failure), the session data is lost and the redirect proceeds as if the save succeeded.
  ThrowsStore-dependent errors: Redis ReplyError (READONLY, OOM, connection lost), PostgreSQL write errors, or any error thrown by store.set() implementation.
  Required handlingCaller MUST check err in the save callback. Redirect flow pattern: req.session.save(function(err) { if (err) return next(err); res.redirect('/dashboard'); }); Proceeding with the redirect without checking err means the user's session data (e.g., userId, role, cart) may not be persisted, causing authentication failures or data loss on the next request.
  costhighin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[2][3]
• req.session.save · save-before-redirect-missing

  warning
  WhenSession data is modified and res.redirect() is called without first calling req.session.save(). The automatic save triggered at response end may not fire before the redirect response is sent in all frameworks/middleware configurations.
  ReturnsThe redirect response is sent immediately. The session save (if it happens at all) runs asynchronously after the response. On the redirect destination, the session data may not yet be persisted, causing the next request to see stale or missing session data.
  Required handlingAlways call req.session.save() explicitly before res.redirect() when session data has been modified. This is documented as a known pattern in express-session README.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[2]
• req.session.reload · reload-session-not-found

  error
  Whenreq.session.reload(callback) called but the session no longer exists in the store. This occurs when: (1) session expired via TTL in Redis/DB, (2) session was destroyed by another server instance or background process, (3) store was flushed.
  ThrowsError: 'failed to load session' — thrown internally when store.get() returns null/undefined
  Required handlingCaller MUST check err in the reload callback. When err is 'failed to load session', the appropriate response is to redirect the user to the login page — their session is gone. In WebSocket handlers: close the connection with a 4401 code and require re-authentication. Ignoring err leaves req.session with stale data from before the reload attempt.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[2][3]
• req.session.reload · reload-store-error

  error
  Whenreq.session.reload(callback) called but the store.get() operation fails with a store error (Redis connection failure, DB timeout) before it can determine if the session exists.
  ThrowsStore-dependent errors: Redis ReplyError, PostgreSQL connection errors. Error propagated verbatim from store.get() to the reload callback.
  Required handlingCaller MUST check err in the reload callback and distinguish between 'failed to load session' (session gone — force re-login) and store connection errors (retry or fail safely).
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[3]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]github.com/expressjs/sessionhttps://github.com/expressjs/session/blob/master/README.md
2. [2]raw.githubusercontent.com/expressjs/sessionhttps://raw.githubusercontent.com/expressjs/session/master/README.md
3. [3]github.com/expressjs/sessionhttps://github.com/expressjs/session/blob/master/session/session.js
4. [4]github.com/expressjs/sessionhttps://github.com/expressjs/session/blob/master/session/store.js