prisma-error-formatter

A flexible and customizable Prisma error formatter to simplify and unify error handling in Prisma Client applications. Easily transform Prisma errors into user-friendly, consistent error messages for your APIs or UI.

Features

• Formats common Prisma Client errors like unique constraint violations, foreign key errors, validation errors, and initialization errors.
• Supports custom error formatting via a callback function.
• Works with Prisma Client’s error classes:
  • PrismaClientKnownRequestError
  • PrismaClientValidationError
  • PrismaClientInitializationError
  • PrismaClientRustPanicError
• Returns structured error messages with clear path and message fields.
• Written in TypeScript with full typings.

Installation

npm install prisma-error-formatter @prisma/client

Basic Usage

import { PrismaClient } from "@prisma/client";
import { PrismaExceptionFormatter } from "prisma-error-formatter";

const prisma = new PrismaClient();
const formatter = new PrismaExceptionFormatter();

async function createUser(email: string) {
  try {
    await prisma.user.create({ data: { email } });
  } catch (error) {
    const formattedErrors = formatter.formatError(error);
    console.error(formattedErrors);
    /*
      Example output:
      [
        {
          path: "email",
          message: "A record with this email already exists."
        }
      ]
    */
  }
}

Using a Custom Formatter

You can provide your own formatting logic by passing a format function when creating the formatter instance:

import { PrismaExceptionFormatter, ErrorMessage } from "prisma-error-formatter";

const formatter = new PrismaExceptionFormatter({
  format: ({ type, error, defaults }) => {
    // Add extra info or change messages based on error type
    if (type === "known" && error.code === "P2002") {
      return [
        {
          path: defaults[0].path,
          message: `Custom: Duplicate value found for ${defaults[0].path}`,
        },
      ];
    }
    // Fallback to default formatting
    return defaults;
  },
});

API

new PrismaExceptionFormatter(options?: { format?: FormatFunction })

Creates a new formatter instance.

• options.format - Optional custom format function. Receives an object with:
  • type: The error type (known, validation, initialization, panic, unknown)
  • error: The original error object
  • defaults: The default formatted error messages (array of { path, message })

Returns formatted errors as an array.

Methods

• formatError(exception: any): ErrorMessage[]
  Automatically detects the Prisma error type and returns formatted messages.

• formatPrismaError(exception: PrismaClientKnownRequestError): ErrorMessage[]
  Formats known Prisma client errors.

• formatQueryError(exception: PrismaClientValidationError | PrismaClientRustPanicError): ErrorMessage[]
  Formats validation or panic errors.

• formatInitializationError(exception: PrismaClientInitializationError): ErrorMessage[]
  Formats database initialization errors.

• formatUnknownError(exception: any): ErrorMessage[]
  Formats unknown errors.

Supported Prisma Error Codes (Known Errors)

• P2002 - Unique constraint violation
• P2003 - Foreign key constraint failure
• P2005, P2006 - Invalid value errors
• P2025 - Record not found

License

MIT © Nurul Islam Rimon

Contribution

Contributions, issues, and feature requests are welcome! Feel free to check

project page

issues page

Related

• Prisma Client
• Prisma Error Codes

Built with ❤️ by Nurul Islam Rimon

🛠️ Open Source Contribution

This project is open to all contributors! Whether you're fixing bugs, improving documentation, adding new formatters, or suggesting ideas — your contribution is highly appreciated.

How to Contribute

1. Fork this repository
2. Create your feature branch:

   git checkout -b feat/my-awesome-feature

3. Commit your changes:

   git commit -m "feat: add my awesome feature"

4. Push to the branch:

   git push origin feat/my-awesome-feature

5. Open a pull request

🙌 Contributions Welcome!

• 📖 Improve the documentation
• 🧪 Add unit tests
• 🔍 Add support for more Prisma error codes
• 💡 Propose new formatting strategies or ideas