Loose ends have been piling up throughout the module, all of the same kind. loadEvent propagates EVENT_NOT_FOUND with next(error). The domain throws INSUFFICIENT_CAPACITY when Sala Bóveda has no tickets left. express.json() rejects a malformed body. The validate middleware from 06-06 calls next(new ValidationError(...)), a class that does not exist yet. And the 404 middleware from 06-03 propagates ROUTE_NOT_FOUND. Nobody picks up any of that. In this lesson we build the common destination: a central handler that turns any failure into a consistent response, and a clear policy about what can be turned into a friendly response and what cannot. It is the module's last piece, and the one that gives meaning to the STATUS_BY_CODE table from Module 4.

1. The error middleware and its four-argument signature
2. Express's default handler
3. Synchronous errors, asynchronous errors and the big Express 5 improvement
4. An error hierarchy of our own
5. STATUS_BY_CODE finds its home
6. Operational errors versus programming errors
7. The complete central handler
8. The 404 middleware
9. Errors outside Express
10. The module checklist

An error middleware is identical to the others except for one thing: it has four parameters.

Express tells the two kinds apart by inspecting fn.length, the function's arity: if it is 4, it is an error handler; otherwise, it is a normal middleware. The symptoms of the bad version are baffling: errors keep showing up in Express's default format, and on correct requests an inexplicable 500 appears, because your function receives (req, res, next) and treats req as if it were an error. If you do not use next, declare it anyway: configure ESLint to allow unused trailing arguments, or call it _next, but do not remove it.

An error handler only catches what is propagated from middleware and routes registered above it. Registering it in the middle means that everything declared afterwards escapes its control: if you write app.use(errorHandler) and only then app.use('/api', createApiRoutes()), the API's errors never reach it. It is the same ordering principle from 06-04, applied to the end of the chain.

An error handler can call next(error) to pass it to the next one, exactly as in the normal chain, which is useful for separating responsibilities: app.use(logError) logs and propagates, app.use(validationErrorHandler) handles only one type or propagates, and app.use(finalHandler) always responds. What must never happen is that the last one does not respond.

If you register none, Express has its own, and it does three sensible things: it uses error.status or error.statusCode if they exist (otherwise it responds 500); it sets whatever headers error.headers carries; and it sends the error body, with a critical difference depending on the environment:

That behavior is correct and it is worth understanding why. A stack trace reveals absolute server paths (/home/deploy/escena-viva/src/...), internal module names, library versions and sometimes fragments of data: a free map for anyone looking for a way in. In development you want to see it in full; in production it must never leave the server. Our own handler keeps exactly that policy, but with our JSON format instead of HTML. A detail that is often ignored: Express decides this from its own env setting, derived from NODE_ENV at startup, so be explicit and do not depend on the framework's internal comparison — that is why our handler consults configuration.isProduction.

Synchronous errors have always been caught by Express: a throw inside a synchronous handler goes to the error handler, no more to it.

In Express 4, the framework called the handler, the handler returned a promise nobody was observing, and the rejection turned into an unhandledRejection with no response to the client: no visible error, no 500, nothing, just the client waiting. If you run into asyncHandler, express-async-handler, catchAsync or wrapAsync in a project, you now know what they are: Express 4 leftovers. In Express 5 they are unnecessary, and removing them strips a layer of noise from every route.

That last row is the exception that does not go away. Express can only observe the promise you hand back to it:

The rule: if an error can happen inside a callback, promisify that operation. It is one more reason to prefer fs.promises and the utilities from Modules 2 and 3.

Until now you created errors with Object.assign(new Error(...), { appCode }). It works, but it does not let you tell types apart with instanceof, it enforces nothing and it gets written differently in every place. Let's formalize it.

Decisions that deserve an explanation:

• this.name = new.target.name: every subclass identifies itself with its own name in the logs, without repeating it by hand; and { cause } preserves the original error when wrapping it, with the full chain for the log and without leaking it to the client.
• An optional this.appStatus lets the domain throw errors with only a code, knowing nothing about HTTP; Error.captureStackTrace removes the constructor from the stack trace, which then starts where the failure really happened; and isOperational = true is the central mark of section 6.

Usage in the domain, which still knows nothing about HTTP:

In Module 4 you wrote src/server/http-errors.js with statusForError, bodyForError and the STATUS_BY_CODE table, which lived scattered across the handlers in responses.js. Now it has a single client: the central handler.

The four-step cascade makes everything fit in the same place: our hierarchy, the codes the domain throws without knowing about HTTP, and third-party errors. For the latter it is also worth normalizing the code, so the client always sees the Escena Viva vocabulary:

This distinction is what decides what gets told to the client and what does not:

How they are told apart in code:

Why a bug returns a silent 500. If a TypeError leaks to the client with its message, you publish the names of your internal variables, the line in the file and, with the stack trace, half your directory tree. On top of that, that message is of no use to the caller: they cannot fix their request because the problem is not in it. A 500 with the request identifier is more useful for everyone: the client knows the failure is yours and has a reference to complain with, and you have the full stack trace in your logs.

Two real responses, one operational and one from a bug:

The second one says absolutely nothing about the failure, but in the server logs the full stack trace sits associated with that very same requestId the client has in front of them. That correlation —the identifier from 06-04 showing up both in the response and in the log— is what turns a useless incident report ("I got an error") into an actionable one ("I got an error, reference 3b71e0a2").

Why it goes before the error handler and after the routes: it is a normal middleware, not an error one, and Express reaches it when no previous route has responded. If you put it before the routes, it would answer 404 to everything; if you put it after the error handler, it would never run. And it propagates instead of responding so that the 404 goes through the same point as every other error and comes out with code, status, requestId and the same format: curl -s localhost:3000/api/does-not-exist returns {"error":{"code":"ROUTE_NOT_FOUND","message":"No route found for GET /api/does-not-exist",...}}. A client that knows how to read your errors should not need a special case for the 404.

Express only sees what happens inside a request; there are two process-level events that escape it:

The temptation is obvious: catch the error, log it and leave the server standing so as not to lose the service. That is a serious mistake, and these are the reasons:

1. The process state is unknown. The exception propagated through a stack that was not expecting it: there are half-finished functions, with partially updated variables. In Escena Viva, an exception in the middle of SalesManager.record can leave the tickets deducted from the capacity but the order never created.
2. Resources are leaked. Every uncaught exception can leave a file descriptor, a socket or a timer unclosed: the process "survives" by degrading until it exhausts the memory.
3. It hides the bug. A server that keeps running badly creates no urgency, and the failure accumulates for weeks. Besides, the default behavior of uncaughtException with no handler is to terminate, and so it should be.

The correct policy, and the one we apply, is: log the whole error → stop accepting new requests → give the in-flight requests a few seconds → terminate the process → let the supervisor restart it. Who restarts it is a matter for the environment, and in Module 11 we will see it with names: PM2 in cluster mode, restart: always in Docker or the automatic restart of a managed container. The application does not restart itself: it dies with dignity and lets the supervisor do its job.

Before calling Escena Viva finished, go over it point by point:

• [ ] createApplication() in src/app.js does not call listen and returns the application; src/server.js creates the http server, starts it and registers the graceful shutdown.
• [ ] src/config/index.js is the only place that reads process.env, and it validates at startup; x-powered-by disabled and trust proxy matching the real deployment.
• [ ] Routers in src/routes/ and controllers in src/controllers/, both free of business logic; routes ordered from specific to generic, with the wildcard last.
• [ ] Every path in every middleware either responds or calls next, and the order is the canonical one from 06-05: id, security, CORS, logging, compression, limits, body, static files, routes, 404, errors.
• [ ] express.json() with limit; express.static with dotfiles: 'ignore'; helmet on with the CSP adjusted to the front end instead of disabled.
• [ ] CORS with an allowlist from configuration, never '*' with credentials; a rate limit on POST /api/orders.
• [ ] Every input validated with a schema at the edge (and in req.validatedData, not by reassigning req.query); the domain keeps its invariants.
• [ ] An error hierarchy in src/errors.js and the central handler last; the stack trace in the response only outside production, and requestId in error responses and in the logs.
• [ ] unhandledRejection and uncaughtException log and terminate gracefully; npm audit clean and dependencies reviewed with the Module 5 criteria.

• Forgetting the fourth parameter. Without next, Express treats your handler as a normal middleware: it never receives errors and it breaks healthy requests.
• Registering it before the routes. It only catches what is declared above it.
• Leaking the stack trace in production or treating bugs as operational errors. You publish system paths and versions, and a detailed TypeError does not help the client but does give you away; check it with NODE_ENV=production before deploying. And do not carry on after an uncaughtException: the process is in an unknown state, so log and terminate.
• Responding when res.headersSent is already true. It triggers Cannot set headers after they are sent; check the flag and delegate to Express.
• Losing the cause when wrapping errors. Use new Error(message, { cause: original }); without it the stack trace starts where you wrapped, not where it failed. And keep the handler itself trivial: if it does a JSON.stringify of something with circular references, it will fail in the worst possible place.
• Tip: test your errors. In Module 9, with supertest, verify that insufficient capacity returns 409 with INSUFFICIENT_CAPACITY, that an invalid :id returns 400 and that a forced bug returns a 500 with no stack trace in production.

Implement the complete src/errors.js and make the domain use it. Check four cases with curl, all of them carrying requestId: GET /api/events/evt-999 → 404 EVENT_NOT_FOUND; POST /api/orders with quantity: 99 → 400 INVALID_DATA with details; POST /api/orders asking for more tickets than are available → 409 INSUFFICIENT_CAPACITY; and GET /api/does-not-exist → 404 ROUTE_NOT_FOUND.

Add an /api/debug/failure route that causes a real TypeError (reading a property of undefined). Check that with NODE_ENV=development the response includes stack, that with NODE_ENV=production it returns the silent 500, and that in both cases stderr shows the full stack trace with the [BUG] prefix and the requestId.

Create two async routes that reject, one wrapped in asyncHandler and one unwrapped, and check in Express 5 that they behave the same. Then write a handler that throws inside a setTimeout and explain why that one does take the process down, and how you would fix it.

Solution 1

Note the difference between the last two: quantity: 99 is a problem of shape (400, detected by the schema without looking at the system's state); asking for 6 tickets when 3 are left is a problem of state (409, only the domain can detect it at that instant). Those are the two levels from 06-06 in action.

Solution 2

In both cases, stderr shows the same full stack trace preceded by [BUG] 3b71e0a2-... GET /api/debug/failure 500 TypeError.

Solution 3

With curl, /a, /b and /d return a 500 with their message —the first two identical— while /c kills the process with an uncaughtException, because its throw happens on a later tick of the event loop (Module 2), on a stack where there is nothing of Express left, and the promise the handler returned —none, in this case— cannot observe that failure. The fix is /d: promisify the wait so that the throw happens inside the async chain Express does observe. The practical conclusion: asyncHandler is unnecessary in Express 5, but promisifying is still mandatory.

This lesson closes Module 6, and Escena Viva is now a complete Express API. Errors finally have a single destination. You know that the error handler is identified by its four parameters and that forgetting the last one turns it into a normal middleware with baffling symptoms; that it is registered last because it only sees what is declared above it; and that Express's default handler filters the stack trace in production and shows it in development, a policy your own handler reproduces with your JSON format. You have seen the big Express 5 improvement —an async handler that rejects reaches the error handler on its own, and asyncHandler becomes an Express 4 relic— with its one remaining exception: whatever happens inside a callback is still your business, and that is why you promisify.

You have built a hierarchy of your own in src/errors.js with ApplicationError and its subclasses ValidationError, ResourceNotFound and StateConflict, and the STATUS_BY_CODE table you wrote in Module 4 has finally found its definitive home: a single point where domain codes, your hierarchy's codes and third-party packages' codes are translated into HTTP statuses. You tell operational errors —expected, explained to the client in detail— apart from programming errors —logged in full, returned as a silent 500 with only the request identifier as a reference. And outside Express, unhandledRejection and uncaughtException log and terminate the process gracefully, without pretending nothing happened, leaving the restart to a supervisor that arrives in Module 11.

Now look at the whole project. createApplication() is tested without starting anything. Configuration is read and validated in a single place. The /api/events, /api/sessions and /api/orders routers live in thirty-line files with their controllers beside them. Your own middleware measures, identifies and controls caching; the third-party ones add security headers, CORS, logging, compression and usage limits. The zod schemas describe exactly what each endpoint accepts. And any failure, wherever it comes from, comes out in the same shape and with an identifier that links it to the server logs. That is a production API. But there is something that has not changed since Module 3, and it is starting to hurt: the data still lives in data/events.json. Every sale rewrites an entire file. Two buyers who hit "buy" at the same time for the last tickets in Sala Bóveda both read the same capacity, both see there is room and both write. The file ends up with the second buyer's sales and the first buyer's disappear, or worse: more tickets are sold than fit in the venue. No schema validation prevents that, no middleware detects it and no error handler can fix it, because it is not an error: it is a race between two writes.

In Module 7 the data stops living in a JSON file. We will start by understanding what a database is and what it brings compared to a file, we will model Escena Viva with MongoDB and Mongoose, we will write the complete CRUD, we will explore relationships and advanced queries, we will look at the SQL world with Sequelize and we will finish with migrations, seeds and —the thing you have been waiting for— transactions, which are exactly the answer to the capacity and overselling problem we have just described. The JSON file has served us for seven modules; it is time to retire it.