DEV Community: Nse569h

DS Express Errors (centralizing errors library) — v1.9.2 Release Notes August 16, 2026

Nse569h — Sun, 16 Aug 2026 19:38:43 +0000

v1.9.2 – August 16, 2026

This release improves production error responses, strengthens JWT error handling, and fixes the TypeScript type for needMappers.

Fixed excessive production response sanitization in Zod, Joi, express-validator, Mongoose, Prisma, and Sequelize mappers
Added separate JWT mapper handling to prevent sensitive JWT error details from being exposed in production
Fixed the TypeScript type for needMappers
Updated README.md documentation
Expanded tests for production-safe mapper responses

What does it mean?

Starting with v1.9.2, production responses from supported library mappers are more useful and informative. Previously, some mapper responses were sanitized more aggressively than necessary, which could remove details that were safe to return to API consumers.

Sensitive information is still protected where required, while development mode continues to provide additional details useful for debugging.

JWT errors are now handled separately. This provides stricter control over what information can appear in production responses and addresses a case where sensitive JWT error details could potentially be exposed.

The TypeScript definition for needMappers has also been corrected. It now uses the appropriate union type instead of being typed as a generic string[], improving type safety and editor autocomplete when configuring mappers.

Finally, the documentation has been updated to make several parts of the library clearer, including how NODE_ENV affects error responses, which errors may be thrown by the library itself, and where to find relevant configuration information.

Website: Official documentation ds-express-errors

Website Changelog: Official ds-express-errors Changelog

Website Roadmap: Official ds-express-errors Roadmap

Have an idea? ds-express-errors discussions

DS Express Errors (centralizing errors library) — v1.9.1 Release Notes August 13, 2026

Nse569h — Fri, 14 Aug 2026 16:56:25 +0000

v1.9.1 – August 13, 2026

Fixed missing types (config.d.ts) for errorClasses (Prisma)
Added missing types (presets.d.ts, index.d.ts) for GatewayTimeout and UnprocessableContent

What does it mean?

For now the TS experience should be more comfortable. Previously errorClasses/Errors presets types do not included required interfaces and in strict TS project I cause bad experience.

Website: Official documentation ds-express-errors

Website Changelog: Official ds-express-errors Changelog

Website Roadmap: Official ds-express-errors Roadmap

Have an idea? ds-express-errors discussions

Automatic Prisma Error Handling in Express with ds-express-errors v1.9.0

Nse569h — Mon, 27 Jul 2026 10:13:22 +0000

Prisma provides useful error classes and error codes, but handling them manually in every Express controller can quickly become repetitive.

A typical controller may need to check whether an error came from Prisma, inspect its code, select an HTTP status, hide database details in production, and return a consistent JSON response.

The ds-express-errors package can handle this centrally. ZERO DEPENDENCIES

It automatically recognizes Prisma errors and converts them into appropriate HTTP responses.

The usual manual approach

Without a centralized error handler, a route may look like this:

const { Prisma } = require('@prisma/client');

app.post('/users', async (req, res) => {
  try {
    const user = await prisma.user.create({
      data: {
        email: req.body.email,
        name: req.body.name
      }
    });

    res.status(201).json(user);
  } catch (error) {
    if (
      error instanceof Prisma.PrismaClientKnownRequestError &&
      error.code === 'P2002'
    ) {
      return res.status(409).json({
        message: 'A user with this email already exists'
      });
    }

    res.status(500).json({
      message: 'Internal server error'
    });
  }
});

This works, but the same checks often appear in several controllers.

With ds-express-errors, Prisma errors can be forwarded to one global middleware instead.

Installation

Install the package in your Express project:

npm install ds-express-errors

This example assumes that Express and Prisma Client are already installed:

npm install express @prisma/client

Example Prisma model

For this example, the "User" model contains a unique email:

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
}

Because email is unique, Prisma will throw error P2002 when someone tries to create another user with the same email.

Configure Prisma error handling

Import the Prisma error classes and pass them to ds-express-errors:

const express = require('express');
const { PrismaClient, Prisma } = require('@prisma/client');

const {
  asyncHandler,
  errorHandler,
  setConfig
} = require('ds-express-errors');

const app = express();
const prisma = new PrismaClient();

app.use(express.json());

setConfig({
  needMappers: ['prisma'],

  errorClasses: {
    Prisma
  }
});

The needMappers option enables only the Prisma mapper.

The errorClasses.Prisma option allows version 1.9.0 to use stricter instanceof checks against the real Prisma error classes.

This option is recommended, but not required. Without it, the library can still use fallback detection based on the error name, Prisma client version, and Prisma error code.

Create a user

The controller no longer needs its own try/catch block:

app.post(
  '/users',
  asyncHandler(async (req, res) => {
    const user = await prisma.user.create({
      data: {
        email: req.body.email,
        name: req.body.name
      }
    });

    res.status(201).json(user);
  })
);

If Prisma throws an error, asyncHandler forwards it to the global error middleware.

For example, creating a user with an existing email produces Prisma error P2002.

ds-express-errors maps it to:

409 Conflict

Example production response:

{
  "status": "fail",
  "message": "Conflict"
}

Handle a missing record

The same setup also works for update and delete operations:

app.patch(
  '/users/:id',
  asyncHandler(async (req, res) => {
    const user = await prisma.user.update({
      where: {
        id: Number(req.params.id)
      },
      data: {
        name: req.body.name
      }
    });

    res.json(user);
  })
);

When the requested user does not exist, Prisma can throw P2025.

The library converts it into:

404 Not Found

Example production response:

{
  "status": "fail",
  "message": "Requested resource not found"
}

Add the global error handler

The error middleware must be registered after all routes:

app.use(errorHandler);

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

The complete application now has one centralized place for handling Prisma and other application errors.

Common Prisma mappings

Supported Prisma Error Codes

The Prisma mapper supports the following Prisma error codes and converts them into consistent development and production responses:

Error Code	Dev Message	Prod Message	HTTP Status
P2000	Value too long for column: ...	Invalid input value	400
P2001	Record does not exist: ...	Resource not found	404
P2002	Unique constraint failed: ...	Conflict	409
P2003	Foreign key constraint failed: ...	Invalid reference	400
P2005	The value stored in the database for the field is invalid for the field's type: ...	Invalid data provided	400
P2006	The provided value for the field is not valid: ...	Invalid input value	400
P2007	Data validation error: ...	Invalid reference	400
P2011	Null constraint violation: ...	Invalid request data	400
P2014	Required relation violation: ...	Invalid relation	400
P2015	A related record could not be found: ...	Requested resource not found	404
P2021	Table does not exist: ...	Internal server error	500
P2022	Column does not exist: ...	Internal server error	500
P2025	Record not found: ...	Resource not found	404
P2027	Multiple errors occurred on the database during query execution: ...	Internal server error	500
P1001	Cannot reach database: ...	Service unavailable	503
P1002	Database timeout: ...	Service unavailable	503
P1003	Database does not exist: ...	Internal server error	500

Development messages preserve useful Prisma details for debugging, while production messages avoid exposing database structure or internal implementation details.

This means controllers do not need a separate switch statement for every supported Prisma error code.

Development and production responses

Set the environment using NODE_ENV:

NODE_ENV=development

In development, the default response can include additional debugging information such as:

{
  "status": "fail",
  "method": "POST",
  "url": "/users",
  "message": "Prisma P2002: [UniqueConstraintError] Unique constraint failed",
  "stack": "Error stack..."
}

In production, stack traces and internal details are hidden:

NODE_ENV=production

{
  "status": "fail",
  "message": "Conflict"
}

For additional mapper logs during development, enable:

DEBUG=true

Example Prisma output. (Dev logging)

[2026-07-23T12:01:34.442Z] POST /prisma/p2003 
MESSAGE: Prisma P2003: [PrismaClientKnownRequestError] Foreign key constraint failed: { modelName: Post }; { field_name: Post_authorId_fkey (index) }  Operation: `prisma.post.create()` 
StatusCode: 400 
Stack: Error: Prisma P2003: [PrismaClientKnownRequestError] Foreign key constraint failed: { modelName: Post }; { field_name: Post_authorId_fkey (index) } 
Operation: `prisma.post.create()`
at BadRequest C:\...
Operational: true

What changed in version 1.9.0?

Version 1.9.0 improved Prisma handling by adding:

strict Prisma error checks using instanceof;
Prisma support inside the errorClasses configuration;
improved detection of PrismaClientInitializationError;
clearer development logs for mapped Prisma errors;
an ESM import fix.

Final example

const express = require('express');
const { PrismaClient, Prisma } = require('@prisma/client');

const {
  asyncHandler,
  errorHandler,
  setConfig
} = require('ds-express-errors');

const app = express();
const prisma = new PrismaClient();

app.use(express.json());

setConfig({
  needMappers: ['prisma'],
  errorClasses: {
    Prisma
  }
});

app.post(
  '/users',
  asyncHandler(async (req, res) => {
    const user = await prisma.user.create({
      data: {
        email: req.body.email,
        name: req.body.name
      }
    });

    res.status(201).json(user);
  })
);

app.patch(
  '/users/:id',
  asyncHandler(async (req, res) => {
    const user = await prisma.user.update({
      where: {
        id: Number(req.params.id)
      },
      data: {
        name: req.body.name
      }
    });

    res.json(user);
  })
);

// Keep the error handler after all routes
app.use(errorHandler);

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Conclusion

Prisma already provides detailed error information, but manually processing every error in every controller adds repeated code.

With ds-express-errors, controllers can focus on database operations while Prisma error recognition, HTTP status mapping, logging, and production-safe responses are handled by centralized middleware.

More information:

DS Express Errors (centralizing errors library) — v1.9.0 Release Notes July 23, 2026

Nse569h — Thu, 23 Jul 2026 14:50:03 +0000

v1.9.0 – July 23, 2026

This release focuses on improving Prisma and Sequelize support, making error detection more reliable while providing clearer development logs.

What's new?

Added strict instanceof checks for Prisma and Sequelize
Configuration property errorClasses now supports Prisma and Sequelize
Fixed ESM import issue
Fixed PrismaClientInitializationError detection
Improved SequelizeConnectionError detection. It now distinguishes between:
- SequelizeConnectionRefusedError
- SequelizeHostNotFoundError
- SequelizeHostNotReachableError
- SequelizeAccessDeniedError

New development log format

Development logs for Prisma and Sequelize have been improved and now include more useful information.

Library Name (Prisma code if available): [Error Name] followed by the formatted message.

Example:

Prisma P2002: [PrismaClientKnownRequestError] Unique constraint failed: { modelName: User }; { target: email }

Sequelize: [SequelizeAccessDeniedError] Access denied for user...

What does it mean?

Starting with v1.9.0, you can enable advanced Prisma and Sequelize detection by providing the corresponding objects in the errorClasses configuration.

Simply import the original object from the library and pass it to setConfig():

const { Prisma } = require('@prisma/client');
const { Sequelize } = require('sequelize');

setConfig({
    errorClasses: {
        Prisma,
        Sequelize
    }
});

Small improvements

ds-express-errors now distinguishes between different SequelizeConnectionError types and maps them individually.

This provides more accurate HTTP responses and more informative development logs when database connection issues occur.

Website: Official documentation ds-express-errors

Website Changelog: Official ds-express-errors Changelog

Website Roadmap: Official ds-express-errors Roadmap

Have an idea? ds-express-errors discussions

DS Express Errors (centralizing errors library) — v1.8.2 Release Notes March 15, 2026

Nse569h — Mon, 27 Apr 2026 07:50:00 +0000

v1.8.2 – March 15, 2026

Fixed missing api import for gracefulHttpClose
Increase internal check to ensure safety handling.
- More internal check for gracefulHttpClose, initGlobalHandlers, setConfig

Small improvements:

Added colors highlights for logger
Expanded internal tests

Website: Official documentation ds-express-errors

Website Changelog: Official ds-express-errors Changelog

Website Roadmap: Official ds-express-errors Roadmap

Have a idea?: ds-express-errors discussions

DS Express Errors (centralizing errors library) — v1.8.0 & v1.8.1 Release Notes

Nse569h — Mon, 12 Jan 2026 13:02:41 +0000

v1.8.0 – January 11, 2026

Added support for user-provided error classes in custom mappers (Zod, Joi)
Added support for turning only needed mappers in config
Rate limiting logger
Express-validator mapper fix incorrect logic
Expand prisma errors ['P2005', P2006, P2007, P2011, P2027]
updated mongoose & sequelize mappers check

What is mean?

Starting with version v1.8.0+, you will be able to choose which mappers to enable so as not to use unnecessary ones, reducing the cost of checking unnecessary mappers.

This version also adds the ability (currently only with Zod and Joi) to pass library classes via setConfig for more rigorous verification. By default, the ds-express-errors library uses duck typing verification, which in turn allows it to remain dependency-free. The ability to pass your own error classes preserves this feature of the library.

Previously, the library's built-in loggers did not have a rate limit, which could cause crashes and freezes.

Small improvements:

New Prisma errors have been added, and the verification logic has been improved in some mappers.

Also, starting with this update, the built-in loggers support colour output for easier reading.

v1.8.1 – January 12, 2026

Fixed missing api import for logDebug
maxLoggerRequests new property in config to set maximal log rate requets per 1 minute (default 100)
Added check for BigIntfor internal safeStringifymethod
Fixed incorrect status code in mongoose mapper
Fixed incorrect status code in sequelize mapper
Logger refactor for customLogger
Added Errors.GatewayTimeout(message)
Fix mapping sequileze now correct map:
- SequelizeOptimisticLockError,
- SequelizeEmptyResultError,
- SequelizeDatabaseError,
- SequelizeConnectionError
- SequelizeTimeoutError

Website: Official documentation ds-express-errors

Website Changelog: Official ds-express-errors Changelog

Website Roadmap: Official ds-express-errors Roadmap

Have a idea?: ds-express-errors discussions

DS Express Errors — v1.7.0 & v1.7.1 Release Notes

Nse569h — Tue, 06 Jan 2026 14:55:30 +0000

In this post, I’m covering updates from v1.7.0 and v1.7.1.
Version 1.7.0 introduced new features and internal improvements, while 1.7.1 focuses on bug fixes, security hardening, and stability.

ds-express-errors v1.7.0 – January 5, 2026

Changes

Added express-validator support
Updated error mapping logic for Mongoose and Prisma
Added validation checks for setConfig
Refactored internal error handling logic
Fixed a logger-related bug

What this means

Version 1.7.0 improves validation support, provides more reliable database error mapping, and strengthens overall logging behavior.

ds-express-errors v1.7.1 – January 7, 2026

This patch release focuses on security, stability, and edge-case fixes discovered shortly after v1.7.0.

Security

Fixed a log injection vulnerability in the internal logger

Fixes & Improvements

Improved validation checks for setConfig to prevent invalid configurations
Fixed a crash in custom mappers when returning Promises or async functions
Enhanced environment configuration checks for safer runtime detection
Added a missing fallback statusCode in defaultErrorAnswer to prevent unexpected 500 responses

Why you should upgrade

If you use custom mappers, custom configuration, or rely on internal logging, upgrading to v1.7.1 is strongly recommended for improved safety and reliability.

Upgrade Notes

Update to the latest version:

npm install ds-express-errors@latest

Additional notes:

express-validator: Make sure validators are properly registered in your routes to take full advantage of the new support.

Custom mappers / setConfig: Ensure your configuration and custom mappers follow the validation rules to avoid runtime errors.

Example usage:

const { setConfig, errorHandler } = require('ds-express-errors');

setConfig({
  customLogger: logger,
  customMappers: [
    (err) => {
      if (err.name === 'newError') {
        return Errors.BadRequest();
      }
    }
  ],
  devEnvironments: ['development', 'dev'],
  formatError: (err, { req, isDev }) => ({
    success: false,
    error: {
      code: err.statusCode,
      message: err.message,
      ...(isDev ? { debug_stack: err.stack } : {})
    }
  })
});

const app = express();
// ... your routes ...
app.use(errorHandler);

More details:

Website & full changelog: ds-express-errors changelog

Don't Let Your Node.js App Die Ugly: A Guide to Perfect Graceful Shutdowns

Nse569h — Fri, 26 Dec 2025 14:43:15 +0000

We spend hours perfecting our CI/CD pipelines, optimizing database queries, and writing clean code. But we often ignore one crucial part of the application lifecycle: Death.

When you deploy a new version of your app to Kubernetes, Docker Swarm, or even PM2, the orchestrator sends a SIGTERM signal to your running process.

If you don't handle this signal, Node.js might terminate immediately. Active HTTP requests are severed, database connections remain open (ghost connections), and transactions might be left in limbo.

Today, I want to show you how to handle this professionally using ds-express-errors, specifically diving deep into its Graceful Shutdown API.

The "Zero-Dependency" Approach

I built ds-express-errors primarily for error mapping, but I included a robust shutdown manager because I was tired of pulling in extra dependencies just to catch a SIGINT.

The library has 0 dependencies, meaning it's lightweight and secure.

The Full Configuration (Not Just the Basics)

Most tutorials only show you how to close the server. But real production apps need more: they need to distinguish between a "Planned Shutdown" (Deployment) and a "Crash" (Uncaught Exception), and they need granular control over exit behavior.

Here is the complete API reference for initGlobalHandlers.

The Setup

First, install the package:

npm install ds-express-errors

Now, let's look at the "Power User" configuration in your entry file (e.g., index.js):

const express = require('express');
const mongoose = require('mongoose');
const { initGlobalHandlers, gracefulHttpClose } = require('ds-express-errors');

const app = express();
const server = app.listen(3000);

// The Complete Configuration
initGlobalHandlers({

    // 1. The HTTP Draining Mechanism
    // Wraps server.close() in a promise that waits for active requests to finish.
    closeServer: gracefulHttpClose(server),

    // 2. Normal Shutdown Logic (SIGINT, SIGTERM)
    // This runs when you redeploy or stop the server manually.
    onShutdown: async () => {
        console.log('SIGTERM received. Closing external connections...');

        // Close DB, Redis, Socket.io, etc.
        await mongoose.disconnect();

        console.log('Cleanup finished. Exiting.');
    },

    // 3. Crash Handling (Uncaught Exceptions / Unhandled Rejections)
    // This runs when your code throws an error you didn't catch.
    onCrash: async (error) => {
        console.error('CRITICAL ERROR:', error);

        // Critical: Send alert to Sentry/Slack/PagerDuty immediately
        // await sendAlert(error); 
    },

    // 4. Exit Strategy for Unhandled Rejections
    // Default: true. 
    // If false, the process continues running even after an unhandled promise rejection.
    // (Recommended: true, because an unhandled rejection can leave the app in an unstable state)
    exitOnUnhandledRejection: true,

    // 5. Exit Strategy for Uncaught Exceptions
    // Default: true.
    // If false, the app tries to stay alive after a sync error. 
    // (High risk of memory leaks or corrupted state if set to false).
    exitOnUncaughtException: true
});

Breakdown of the Options

Let's dissect what we just wrote. The initGlobalHandlers function accepts an options object with these specific keys:

closeServer

Type: Function (Async)

This is where you handle the HTTP layer. The library provides a helper gracefulHttpClose(server) which listens for the abort signal and handles the callback hell of the native Node.js server.close(). It ensures no new connections are accepted, but keeps the process alive until existing users finish their requests.

onShutdown

Type: Function (Async)

This is for your business logic cleanup. It is triggered only by system signals (SIGINT, SIGTERM, SIGQUIT).
This is the "Happy Path" of death. You should:

Close Database connections.
Flush logs.
Cancel long-running jobs.

onCrash

Type: Function (Async)

This is unique. Many libraries treat a crash the same as a shutdown. But ds-express-errors separates them. onCrash is triggered by uncaughtException or unhandledRejection.

Why separate them?

In onShutdown, you are calm. In onCrash, the house is on fire. You might not want to wait for a graceful DB disconnect; you might want to fire a "HELP ME" alert to Slack and die immediately.

exitOnUnhandledRejection & exitOnUncaughtException

Type: Boolean (Default: true)

By default, the library follows Node.js best practices: fail fast. If the process state is corrupted (unhandled error), it logs the error, runs onCrash, and exits with code 1.

However, if you have a specific requirement to keep the process alive (perhaps you have an external supervisor or a very specific resilience strategy), you can toggle these to false.

The Safety Net: Timeouts

What if your onShutdown logic hangs? What if mongoose.disconnect() never resolves?

You don't want your pod to hang in the "Terminating" state forever (Kubernetes will eventually SIGKILL it anyway).

ds-express-errors wraps your shutdown logic in a 10-second timeout. If your cleanup functions don't resolve by then, it forces an exit to prevent zombie processes.
Conclusion

Handling process termination is part of being a senior engineer. It distinguishes a "hobby project" from a reliable distributed system.

With ds-express-errors, you don't need complex boilerplate. You get a fully typed, zero-dependency solution that handles both graceful shutdowns and critical crashes out of the box
.
Links:

Happy coding (and happy shutting down)! 🔌

I finally stopped writing try-catch in every Express controller (and you should too)

Nse569h — Thu, 25 Dec 2025 01:15:36 +0000

Let’s be honest for a second. We all hate writing error handling in Express.

You start with a beautiful, clean controller function. It’s supposed to do one thing: register a user. But then reality hits. You need to validate the body. You need to check if the email exists in MongoDB. You need to catch unexpected crashes.

Before you know it, your 5-line function has turned into a 50-line spaghetti monster wrapped in a massive try/catch block.

I used to copy-paste this boilerplate from project to project until I found a cleaner way. Recently, I started using ds-express-errors, and it actually made coding backend logic fun again.

Here is how I cleaned up my code.

The "Old Me" Approach 🍝

This is actual code from one of my old projects. It hurts just looking at it.

// controllers/authController.js
const User = require('../models/User');

exports.register = async (req, res, next) => {
  try {
    // 1. Manually checking for missing fields... boring.
    if (!req.body.email || !req.body.password) {
        return res.status(400).json({ status: 'error', message: 'Missing fields' });
    }

    const newUser = await User.create(req.body);

    res.status(201).json({ success: true, data: newUser });

  } catch (err) {
    // 2. The "Error parsing hell"
    // Is it a validation error? A duplicate key? Who knows?
    if (err.name === 'ValidationError') {
        const msg = Object.values(err.errors).map(val => val.message).join(', ');
        return res.status(400).json({ success: false, message: msg });
    }

    if (err.code === 11000) {
        return res.status(409).json({ success: false, message: 'Email already taken' });
    }

    // 3. Just giving up
    console.error(err);
    res.status(500).json({ success: false, message: 'Server Error' });
  }
};

If you have 20 controllers, you have 20 copies of this catch block. If you change your error response format, you have to refactor everything.

The "New Me" Approach ✨

I switched to using ds-express-errors because it specifically handles the heavy lifting for libraries I already use (Mongoose, Prisma, Zod).

Here is the exact same controller rewritten.

// controllers/authController.js
const User = require('../models/User');
const { asyncHandler, Errors } = require('ds-express-errors'); //

// No try-catch. Just logic.
exports.register = asyncHandler(async (req, res) => {
    const newUser = await User.create(req.body);

    // Need to throw a custom error? Easy.
    if (!newUser) {
        throw Errors.BadRequest('Could not create user'); //
    }

    res.status(201).json({ success: true, data: newUser });
});

That’s it.

"Wait, what happens if MongoDB throws an error?"

That's the cool part. The library's middleware automatically detects that it's a Mongoose error.

If it's a Duplicate Key (E11000) -> It sends a 400 Bad Request with "Duplicate field value entered".
If it's a Validation Error -> It joins your validation messages and sends a 400.
If it's a JWT Error -> It sends a 401 Unauthorized.

I didn't have to write a single if statement for that.

Setup is stupidly simple

I hate complex configs. Luckily, this is just a middleware drop-in.

In your app.js or index.js:

const express = require('express');
const { errorHandler } = require('ds-express-errors'); //

const app = express();

// ... define your routes here ...

// Just put this at the END of your middleware chain
app.use(errorHandler);

app.listen(3000, () => console.log('Server is flying 🚀'));

Bonus: Sleeping better at night (Graceful Shutdown) v1.5.0

Another thing I used to ignore was proper server shutdown. If my app crashed or Docker restarted the container, active requests would just get cut off. Users would lose data.

This lib has a built-in helper for this. It ensures the server closes connections properly before dying.

const { initGlobalHandlers, gracefulHttpClose } = require('ds-express-errors'); //

const server = app.listen(PORT);

initGlobalHandlers({
    // Wraps the server close method safely
    closeServer: gracefulHttpClose(server),

    // Close your DB connections here
    onShutdown: async () => {
        console.log('Closing DB...');
        await mongoose.disconnect();
    }
});

Now, if I get a SIGTERM or an unhandled rejection, the app cleans up its mess before exiting.

Verdict

There are a million error handlers out there, but I stick with this one because it has zero dependencies and supports TypeScript out of the box. It just removes the noise from my code.

Link: ds-express-errors documentation

Standardizing Express.js Error Handling with One Library

Nse569h — Fri, 05 Dec 2025 10:52:21 +0000

If you've been working with Express.js error handling for a while, you know the struggle. What starts as a simple project quickly turns into controllers filled with repetitive try/catch blocks and scattered status code logic:

// The "Bad" Way
app.post('/users', async (req, res) => {
  try {
    // ... logic
  } catch (error) {
    console.error(error);
    if (error.code === 'P2002') { // Prisma unique constraint
        return res.status(400).json({ message: 'User already exists' });
    }
    // ... 10 more if/else checks
    res.status(500).json({ message: 'Something went wrong' });
  }
});

It's repetitive, hard to maintain, and prone to bugs. I got tired of copy-pasting error handling logic between my projects, so I built a tool to fix it once and for all.

Meet ds-express-errors zero dependencies library!

Why you need centralized error handling in Express.js

Express developers often search for best practices to avoid repetitive try/catch blocks, inconsistent status codes, and unreadable controller logic. ds-express-errors solves these issues by providing a structured, predictable, and type-safe error handling flow for Express.js applications.

Here is why I think it's worth checking out:

Ready-to-use Error Presets for Express.js 🛠️

Forget about remembering if "Forbidden" is 401 or 403. Just use the presets.

import { Errors } from 'ds-express-errors';

if (!user) {
  throw Errors.NotFound('User not found'); // Automatically sends 404
}

if (!user.hasAccess) {
  throw Errors.Forbidden('Access denied'); // Automatically sends 403
}

Auto-Mapping for Zod, Joi, Prisma, Mongoose, Sequelize, JWT Errors 🪄

This is my favorite part. If you use Zod, Joi, Prisma, Mongoose, Sequelize, JWT, the library automatically detects their native errors and converts them into readable HTTP 400 Bad Requests.

Example with Zod:
You don't need to manually parse error.issues.

Input (Invalid):

{
    "issues": [
        {
            "path": ["user", "email"],
            "message": "Invalid email address"
        },
    ],
    "name": "ZodError"
}

Output (Automatic):

{
  "status": "fail",
  "method": "GET", // showed when development environment,
  "url": "/login", // showed when development environment,
  "message": "Validation error: user.email: Invalid email address;",
  "stack": // showed when development environment,
}

No More try/catch in Express Controllers

With the included asyncHandler, your controllers become clean again.

import { asyncHandler, Errors } from 'ds-express-errors';

const createUser = asyncHandler(async (req, res) => {
  const user = await db.create(req.body); // If this throws, it's handled automatically!
  res.json(user);
});

Graceful Shutdown in Node.js & Express.js (v1.4.1)

A graceful shutdown in Express.js ensures your Node.js application can handle critical process-level errors such as uncaughtException and unhandledRejection without immediate crashes.

This approach allows the server to close database connections safely and predictably before the application stops, improving reliability and stability in production.

Implementing a proper Node.js graceful shutdown mechanism helps maintain data integrity and prevents abrupt termination of your Express server.

import { initGlobalHandlers } from 'ds-express-errors';

initGlobalHandlers({
  // Optional: Prevent exit on unhandledRejection (default: true)
  exitOnUnhandledRejection: true,

  // Async callback with error access
  onCrash: async (err) => {
    console.error('CRASH DETECTED:', err.message); // Access the error!

    // Send alert to Sentry/Telegram
    await sendAlertToAdmin(err);

    // Close resources
    await db.disconnect();
    console.log('Cleanup finished.');

    // The library will automatically execute process.exit(1) after this function
  }
});

Configuration (Custom Response Format)

You can customize the structure of the error response sent to the client. This is useful if you need to adhere to a specific API standard (e.g., JSON:API) or hide certain fields.

Customize the dev environment by using devEnvironments: []

Looking to manage an error from a library that isn’t natively supported? Or do you want to modify the standard behavior? You can pass an array of customMappers.

Use setConfig before initializing the error handler middleware.

import { setConfig, errorHandler } from('ds-express-errors');

// Optional: Customize response format
setConfig({
// Your Winston/Pino logger
    customLogger: logger, 
    customMappers: [
        (err, req) => {
            if (err.name === 'newErrorWithReq') {
                return Errors.Forbidden(`[${req.baseUrl}] ${err.message}`)
            }
            //... other if
        }
    ],
    devEnvironments: ['development', 'dev'],
    formatError: (err, {req, isDev}) => {
        return {
            success: false,
            error: {
                code: err.statusCode,
                message: err.message,
                // Add stack trace only in development
                ...(isDev ? { debug_stack: err.stack } : {})
            }
        };
    }
});

const app = express();
// ... your routes ...
app.use(errorHandler);

Default Format
If no config is provided, the library uses the default format:

{
  "status": "error", // or 'fail'
  "method": "GET", // showed when development environment
  "url": "/api/resource", // showed when development environment
  "message": "Error description",
  "stack": // showed when development environment,
}

Default Config Format

let config = {
    customMappers: [],
    devEnvironments: ['dev', 'development'],
    formatError: (err, {req, isDev}) => ({ 
        status: err.isOperational ? 'fail' : 'error',
        message: err.message,
        ...(isDev ? { 
            method: req.method,
            url: req.originalUrl,
            stack: err.stack
         } : {})
    })
}

📦 How to use it?

Installation is standard:

npm install ds-express-errors

📚 Documentation

I've built a full documentation website where you can see advanced usage, API references, and more examples:

👉ds-express-errors official documentation

FAQ

1. Does ds-express-errors replace Express’s default error handler?

Yes—it extends it with a fully typed and configurable error-handling layer.

2. Does it work with TypeScript?

Absolutely. The library is built with full TypeScript support.

3. Can I use it with Zod, Joi, Prisma, Mongoose, Sequelize, express-validator, or JWT?

Yes—the auto-mapping feature automatically converts their native errors into consistent HTTP responses.

Conclusion

This library allowed me to finally unify and simplify Express.js error handling across my Node.js projects. If you want predictable status codes, type-safe errors, and cleaner controllers without endless try/catch blocks, ds-express-errors can save you a lot of time.

Please don't hesitate to try it out and share your feedback. A star on GitHub means a lot. ❤️