Error Handling in Mongoose Operations

A Mongoose-backed Express API has a well-defined set of errors it can produce — ValidationError, CastError, duplicate key errors, and unexpected operational errors. Each has a known shape, a correct HTTP status code, and a message that your React frontend can display usefully. In this lesson you will verify that your global error handler correctly handles every Mongoose error type, write test cases that deliberately trigger each error, and confirm that no scenario returns an unhelpful 500 response when a more specific 400 or 409 is appropriate.

Mongoose Error Types Catalogue #

The Complete errorHandler — Handling All Mongoose Errors #

// server/src/middleware/errorHandler.js
const errorHandler = (err, req, res, next) => {
  // Always log the full error server-side
  if (process.env.NODE_ENV === 'development') {
    console.error(`[ERROR] ${err.name}: ${err.message}`);
    console.error(err.stack);
  } else {
    console.error(`[ERROR] ${err.name}: ${err.message}`);
  }

  let statusCode = err.statusCode || 500;
  let message    = err.message    || 'Internal Server Error';
  let isOperational = !!err.isOperational;

  // ── Mongoose: invalid ObjectId ─────────────────────────────────────────────
  if (err.name === 'CastError' && err.kind === 'ObjectId') {
    statusCode    = 400;
    message       = `Invalid ID format: '${err.value}'`;
    isOperational = true;
  }

  // ── Mongoose: schema validation failed ─────────────────────────────────────
  if (err.name === 'ValidationError') {
    statusCode    = 400;
    const errors  = Object.values(err.errors).map(e => ({
      field: e.path, message: e.message,
    }));
    message       = errors.map(e => e.message).join('; ');
    isOperational = true;
    return res.status(statusCode).json({ success: false, message, errors });
  }

  // ── MongoDB: duplicate key ──────────────────────────────────────────────────
  if (err.code === 11000) {
    const field   = Object.keys(err.keyValue || {})[0] || 'field';
    const value   = err.keyValue?.[field];
    statusCode    = 409;
    message       = `${field.charAt(0).toUpperCase() + field.slice(1)} '${value}' already exists`;
    isOperational = true;
  }

  // ── JWT: invalid signature ─────────────────────────────────────────────────
  if (err.name === 'JsonWebTokenError') {
    statusCode    = 401;
    message       = 'Invalid token — please log in again';
    isOperational = true;
  }

  // ── JWT: expired ───────────────────────────────────────────────────────────
  if (err.name === 'TokenExpiredError') {
    statusCode    = 401;
    message       = 'Your session has expired — please log in again';
    isOperational = true;
  }

  // ── Payload too large ──────────────────────────────────────────────────────
  if (err.type === 'entity.too.large') {
    statusCode    = 413;
    message       = 'Request body too large';
    isOperational = true;
  }

  // In production: hide internal details for non-operational errors
  if (process.env.NODE_ENV === 'production' && !isOperational) {
    message = 'An unexpected error occurred';
  }

  res.status(statusCode).json({
    success: false,
    message,
    ...(process.env.NODE_ENV === 'development' && {
      errorName: err.name,
      stack:     err.stack,
    }),
  });
};

module.exports = errorHandler;

Test Cases — Triggering Each Error Type #

── ValidationError ─────────────────────────────────────────────────────────
POST /api/posts  Authorization: Bearer <valid_token>
Body: { "body": "Content without a title" }

Expected: 400
{ "success": false, "message": "Post title is required",
  "errors": [{ "field": "title", "message": "Post title is required" }] }

── CastError (invalid ObjectId) ────────────────────────────────────────────
GET /api/posts/not-a-valid-id

Expected: 400
{ "success": false, "message": "Invalid ID format: 'not-a-valid-id'" }

── Duplicate Key Error (email already exists) ──────────────────────────────
POST /api/auth/register
Body: { "name": "Jane", "email": "existing@email.com", "password": "Test@1234" }

Expected: 409
{ "success": false, "message": "Email 'existing@email.com' already exists" }

── Not Found (AppError 404) ─────────────────────────────────────────────────
GET /api/posts/64a1f2b3c8e4d5f6a7b8c9d0  (valid ObjectId, no matching document)

Expected: 404
{ "success": false, "message": "Post not found" }

── Unauthorized (no token) ─────────────────────────────────────────────────
POST /api/posts  (no Authorization header)

Expected: 401
{ "success": false, "message": "No token provided — please log in" }

── Forbidden (valid token, not the owner) ──────────────────────────────────
DELETE /api/posts/:id  (authenticated as user who does not own the post)

Expected: 403
{ "success": false, "message": "Not authorised to delete this post" }

Using orFail() for Cleaner Not-Found Handling #

// Instead of:
const post = await Post.findById(id);
if (!post) throw new AppError('Post not found', 404);

// You can use .orFail():
const post = await Post.findById(id)
  .orFail(new AppError('Post not found', 404));
// If document is not found → throws the provided error automatically
// asyncHandler catches it → passed to errorHandler → 404 response ✓

Common Mistakes #

Mistake 1 — Returning 500 for a known Mongoose error type #

❌ Wrong — errorHandler does not handle CastError specifically:

// errorHandler without CastError handling
const errorHandler = (err, req, res, next) => {
  res.status(500).json({ message: err.message });
  // GET /api/posts/invalid-id → 500 "Cast to ObjectId failed..."
  // Should be 400 "Invalid ID format"
};

✅ Correct — handle each Mongoose error type explicitly in the global error handler.

Mistake 2 — Sending raw Mongoose ValidationError to the client #

❌ Wrong — the raw err object exposed to React:

res.status(400).json({ error: err });
// Sends the entire Mongoose error object including internal paths,
// validators array, stack trace, etc. — too much information to the client

✅ Correct — extract and format only the user-facing messages:

const errors = Object.values(err.errors).map(e => ({ field: e.path, message: e.message }));
res.status(400).json({ success: false, message: '...', errors }); // ✓ clean format

Mistake 3 — Not testing error paths in Postman #

❌ Wrong — only testing the happy path and discovering error handling bugs in production.

✅ Correct — for every route, create at minimum these test scenarios in Postman: valid input, missing required fields, invalid ObjectId, no token, wrong token, not owner. Run the collection before every deployment.

Quick Reference — Error Types and Status Codes #