skip to content

In an Express 5 app, an async passport-local verify callback throws during a database outage and the whole Node process exits; why doesn't Express 5 catch it, and what is the fix?

level: seniorimportance: should knowfreq 42%

answer

  1. who receives the rejected promise
  2. Passport's middleware returns nothing
  3. try/catch only sees synchronous throws
  4. unhandled rejection mode is throw

basics

~20 s

Express 5 forwards only rejections of a promise the middleware returns. passport.authenticate returns nothing and passport-local catches only synchronous throws, so the rejection goes unhandled and Node's default throw mode exits. Catch inside verify and call done(err).

solid answer

~40 s

Express 5's router calls each handler and, if the handler **returns** a promise that rejects, calls `next(err)`. The middleware from `passport.authenticate()` returns nothing: it calls the strategy synchronously, and `passport-local` calls your verify inside a `try/catch` that only catches synchronous throws. An `async` verify never throws synchronously; it returns a rejected promise that nobody holds. Node's default `--unhandled-rejections` mode has been `throw` since v15, so the rejection becomes an uncaught exception and the process exits. The fix is to catch inside the verify callback and call `done(err)`, which Passport forwards to `next(err)` and your error middleware. Do not catch and call `done(null, false)`: that turns an outage into a wrong-password 401 and hides it.

go deeper

for a junior

Remember that an async verify callback must still finish through done, and that done(err) is how an outage is reported.

for a middle

Explain which errors Express 5's router forwards, a synchronous throw or a returned rejected promise, and why Passport's middleware returns neither for an async verify.

for a senior

Diagnose the exit from the stack trace and the unhandled-rejection default, fix verify with a narrow try and done(err), and reject the done(null, false) catch-all that hides outages.

for a principal

Make settle-through-done a review rule for every strategy, and decide whether the team wraps callback-style libraries in one shared adapter instead of per-strategy care.

## What Express 5 actually forwards Express 5's router (the `router` package it depends on) wraps every handler call. In `Layer.prototype.handleRequest` it calls the handler inside a `try/catch`, and if the call **returned a promise**, it attaches a rejection handler that calls `next(err)`. That gives you two cases that reach your error middleware: - the handler throws synchronously, caught by the `try/catch`; - the handler returns a promise that later rejects, caught by the attached rejection handler. Express 4 had only the first; forwarding a returned rejection is new in Express 5. Neither version can forward a rejection from a promise the handler never returned. ## Why Passport's middleware falls outside both cases Follow the call chain for `app.post('/login', express.urlencoded(), passport.authenticate('local'), handler)`: 1. The router calls the function `passport.authenticate('local')` returned. That function sets up the strategy's actions and calls `strategy.authenticate(req, options)`. It **returns `undefined`**, so the router has no promise to watch. 2. `passport-local`'s `authenticate` reads the fields and calls `this._verify(username, password, verified)` inside its own `try/catch`. A synchronous `throw` in a classic verify function is caught there and turned into `this.error(ex)`. 3. Your verify is an `async` function. Calling it runs until the first `await` and **returns a promise**; when the database call rejects, that promise rejects. `passport-local` ignores the return value, so nothing is attached to it. 4. Node sees a rejected promise with no handler. Its `--unhandled-rejections` mode has defaulted to `throw` since Node 15: unless an `unhandledRejection` listener is installed, the rejection is raised as an uncaught exception, and with no `uncaughtException` handler the process exits with code 1. Every in-flight request on that process is cut off. | Where the error happens | Who catches it | Result | |---|---|---| | synchronous throw in a classic verify | `passport-local`'s `try/catch` | `this.error` then `next(err)` | | `done(err)` called from verify | the strategy's `verified` function | `next(err)` | | rejection from an `async` verify | nobody | unhandled rejection, process exits | Wrapping the route in an async-aware helper does not help, because the rejected promise is not on the route's return path; it belongs to the verify call deep inside the strategy. ## The fix Keep the verify callback `async` if you like, but make it settle through `done` on every path: ```js passport.use(new LocalStrategy(async (username, password, done) => { let user; try { user = await findUserByUsername(username); if (user && !(await passwordMatches(user, password))) user = null; } catch (err) { return done(err); } if (!user) return done(null, false, { message: 'Incorrect username or password.' }); return done(null, user); })); ``` Points that make this version correct: - The `try` wraps only the awaited lookups, and the success and failure `done` calls sit outside it, so a problem after `done(null, user)` cannot be mistaken for a lookup error and trigger a second `done` call. - `done(err)` sends the outage to `next(err)`, where your error middleware logs it and answers 500. - A missing user and a wrong password share one failure message. ## The tempting wrong fix A catch-all that calls `done(null, false)` stops the crash and creates a quieter problem: - An outage now looks like a wrong password: users get a 401 or a `failureRedirect` back to the form, and retry. - Any lockout or rate-limit logic that counts failed logins starts locking out real users. - Nothing reaches the error middleware, so error logging and alerting never see the incident. The distinction `done` exists to make, failure versus error, is exactly what this collapses. ## Related upgrade trap The same Express 5 upgrade can break a `passport-local` form in a different way. Express 5's `express.urlencoded()` defaults to `extended: false`, so a field posted as `user[email]` is parsed as a flat key named `user[email]`. If the strategy was configured with `usernameField: 'user[email]'`, it looks for a nested object, finds nothing, and every login fails with `Missing credentials` and a 400. Set `extended: true` on that parser or post flat field names.

  • After the Express 5 upgrade, a form that posts user[email] gets 400 from passport-local on every login. Why?
    Express 5's `express.urlencoded()` defaults to `extended: false`, so `user[email]` arrives as a flat key rather than a nested object. A strategy configured with `usernameField: 'user[email]'` looks for `req.body.user.email`, finds nothing, and fails with `Missing credentials` and status 400. Set `extended: true` on that parser, or post a flat field name and configure it.
  • Would adding process.on('unhandledRejection') be a reasonable fix?
    No. It keeps the process alive, but the login request never settles: no `done` call means no response, so the client waits until a timeout. It also hides the defect for every other code path. The fix belongs in the verify callback, which must end every path with exactly one `done` call.

  • Express 5 catches every promise rejection raised during a request
  • Passport awaits the promise an async verify callback returns
  • Catching the outage and calling done(null, false) is a safe fix
  • Express 4 already forwarded rejected promises to error middleware
  • An unhandled rejection in Node only prints a warning by default

Assumes Express 5, whose router forwards a rejection only from a promise a handler returns; Express 4 forwarded none, and Passport's middleware returns nothing in either.