Express.js Development Error Handler

Common errors

• Error: Can't set headers after they are sent to the client

  cause This error occurs when a previous middleware or route handler attempts to send a response or set headers *before* an error is thrown and caught by `errorhandler`. If `errorhandler` then tries to send its own error response, the headers have already been sent.
  fix Ensure that response logic in your middleware and routes is robust and does not send multiple responses. If an error occurs, call `next(err)` and let the error handling middleware take over. Avoid `res.send()` or `res.end()` followed by `next(err)` in the same block.

• TypeError: app.use is not a function

  cause This indicates you are trying to use `app.use()` on an object that is not an Express or Connect application instance. This might happen if you are using a plain HTTP server without proper middleware setup.
  fix Make sure `app` is initialized as an Express or Connect application, e.g., `const express = require('express'); const app = express();` or `const connect = require('connect'); const app = connect();`.

Warnings

• breaking The `log` option's default behavior changed in `1.5.0`. Previously, it would always log to `console.error`. Now, if `process.env.NODE_ENV === 'test'`, the default `log` value becomes `false` (no console logging). Explicitly set `log: true` to force console logging in 'test' environments.
  Fix: If you rely on console logging in test environments, explicitly set `log: true` in the `errorhandler` options: `app.use(errorhandler({ log: true }))`.
• gotcha This middleware is strictly for development environments. It exposes full error stack traces and internal details of any object passed as an error, which can be a severe security vulnerability if used in production.
  Fix: Always conditionally enable `errorhandler` based on `process.env.NODE_ENV`. For production, use a more generic error handling middleware that does not expose sensitive information, e.g., `app.use(function (err, req, res, next) { res.status(500).send('Something broke!'); })`.
• gotcha The `log` option function is invoked *after* the response has been written. This means attempting to modify the response (e.g., setting headers, sending a different body) within the custom `log` function will have no effect.
  Fix: The `log` function should only be used for side-effects like logging to a file, database, or sending notifications. Any response modification must occur *before* the `errorhandler` middleware sends its response.
• gotcha When a non-`Error` object is passed as an error (e.g., `next('something broke')` instead of `next(new Error('something broke'))`), `errorhandler` will attempt to display its contents using `util.inspect`. While useful for debugging, this might expose unexpected or very verbose object structures.
  Fix: Always pass actual `Error` objects to `next()` when signaling an error, e.g., `next(new Error('Description'))` or a custom error class extending `Error`. This provides better control over what information is presented.

Install

• npm install errorhandler npm
• yarn add errorhandler yarn
• pnpm add errorhandler pnpm

Imports

• errorhandler
  wrong:

  import errorhandler from 'errorhandler'

  correct:

  const errorhandler = require('errorhandler')

  This package is CommonJS-first and primarily used with `require()`. While Node.js allows `import errorhandler from 'errorhandler'` in ESM contexts, the official examples use `require`.
• errorHandlerMiddleware
  wrong:

  app.use(new errorhandler())

  correct:

  app.use(errorhandler())

  The `errorhandler` function itself returns the middleware; it's not a class that needs `new`.
• logOption
  wrong:

  app.use(errorhandler({ logger: customLogger }))

  correct:

  app.use(errorhandler({ log: customLogger }))

  The option to provide a custom logging function is named `log`, not `logger`.

Quickstart

This example demonstrates how to integrate `errorhandler` into a Connect (or Express) application, configuring it to only run in a development environment and providing a custom logging function that sends desktop notifications for errors.

const connect = require('connect');
const errorhandler = require('errorhandler');
const notifier = require('node-notifier');

const app = connect();

// Assumes NODE_ENV is set by the user, e.g., via 'NODE_ENV=development node app.js'
if (process.env.NODE_ENV === 'development') {
  // Only use in development to display detailed error information
  app.use(errorhandler({
    log: (err, str, req, res) => {
      // Custom logging function, e.g., sending system notifications
      const title = `Error in ${req.method} ${req.url}`;
      notifier.notify({
        title: title,
        message: str,
        // Optionally, add a sound or icon for better visibility
        sound: true, 
        wait: true
      });
      // Also log to console for standard debugging flow
      console.error(str);
    }
  }));
}

// Example route that intentionally throws an error
app.use('/error', (req, res, next) => {
  next(new Error('This is a simulated error for demonstration!'));
});

// Fallback for non-error requests
app.use((req, res, next) => {
  res.end('Hello from a non-error path. Try /error to see the error handler in action.');
});

const port = 3000;
app.listen(port, () => {
  console.log(`Server running on http://localhost:${port}`);
  console.log('Ensure NODE_ENV is set to \'development\' to enable errorhandler.');
});