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?
answer
- who receives the rejected promise
- Passport's middleware returns nothing
- try/catch only sees synchronous throws
- unhandled rejection mode is throw
basics
~20 sExpress 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 sExpress 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
Remember that an async verify callback must still finish through done, and that done(err) is how an outage is reported.
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.
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.
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.