Express Error Handling, Logging and File Uploads in Node.js

Node.js Error Handling, Logging & File Upload Architecture

Imran, a backend developer in Jodhpur, looks after the API for a small handicraft shop that sells blue pottery, leather mojaris and bandhani dupattas online. One morning the owner calls: the site was down for part of the night and customers could not place orders. Imran opens the server log, expecting answers. The only line from around the crash is:

something went wrong

That line comes from a console.log('something went wrong') he wrote months ago inside a catch block. There is no stack trace, no URL, no time, no request id and no customer. He cannot tell which request broke the server, whether it was a bug or bad input, or whether it will happen again tonight. How should a Node.js API catch errors, answer the client properly, and leave behind a log that actually explains what happened? That is what this post covers: error types, a custom error class, Express error middleware, async errors in Express 5, logging with morgan and winston, input validation, and safe file uploads with multer. Every sample was run on Node.js v24 with Express 5, and the outputs shown are real.

What Is Error Handling?

Error handling is how an application detects a problem, decides what it means, answers the user sensibly and records what happened, instead of crashing or failing silently. Think of a hospital emergency department. Patients arrive with all kinds of problems, but the staff do not panic each time. They follow a routine: receive the patient, identify the problem, treat it, and write it in the record. A good backend does the same with errors: catch, classify, respond, log, and keep serving everyone else.

Errors are not rare events you can ignore. Databases disconnect, networks time out, users type nonsense, third-party payment gateways go slow, and every developer ships bugs. Without proper handling, the application crashes, users see confusing messages, internal details leak to attackers, and debugging turns into guesswork. One bad request taking down the whole server, as it did for Imran, affects every customer who is online at that moment.

Types of Errors in a Node.js Backend

Most errors in a backend fall into a few groups. Knowing the group tells you who caused it, which status code to send, and whether it needs a code fix.

TypeExampleWhen you notice itUsual response
Syntax errorA missing }When the file loads, before any code runsNone: the app does not start. Fix the code.
Runtime erroruser.name when user is nullWhile the code runs500, log the stack, fix the bug
Validation error{"email": "abc"}, a negative priceWhen a request arrives400 with the field and reason
Database errorConnection refused, timeout, duplicate keyWhen you call the database500 or 503 (409 for duplicates); never show the SQL
Authentication errorMissing or expired token, wrong passwordIn the auth middleware401 Unauthorized
Authorization errorA seller tries to delete another seller's productAfter identity is known403 Forbidden

A syntax error stops Node.js from even starting the file. Here is a real one: the object is missing its closing brace, so Node.js reaches the next line and does not know what to do with it.

const user = {
  name: "Imran"
console.log(user);

// SyntaxError: Unexpected identifier 'console'
// (the process exits with code 1 before any line runs)

A runtime error happens while the program is running. The code loads fine, then fails on a particular input. These are the common ones in backends, because the data decides whether the line works.

try {
  const user = null;
  console.log(user.name);
} catch (err) {
  console.log(err.name);                // TypeError
  console.log(err.message);             // Cannot read properties of null (reading 'name')
  console.log(err instanceof TypeError); // true
}

Authentication asks "who are you?" and authorization asks "what are you allowed to do?". A request with no token fails authentication (401). A logged-in seller who tries to open the admin reports fails authorization (403). The Authentication, Authorization, JWT and Password Hashing post explains how tokens are checked; here we only care about how those failures are reported.

Operational Errors vs Programmer Errors

This is the most useful distinction in error handling, and much of the Node.js community's advice on errors is built on it. An operational error is an expected problem in a correctly written program: the user sent bad data, the product does not exist, the database is down, the payment gateway timed out. You cannot prevent these, so you handle them: send a clear status code and message, maybe retry, and move on. A programmer error is a bug: calling a function that does not exist, reading a property of undefined, forgetting an await. You cannot "handle" a bug at runtime; you log it with its stack trace, return a generic 500, and fix the code.

Operational errorProgrammer error
ExamplesInvalid password, missing product, network timeout, invalid request bodyReferenceError: cart is not defined, wrong function call, incorrect logic
Who caused itThe user or the environmentThe developer
What the client seesA specific message and a 4xx (or 503)A generic "Something went wrong" and 500
What you doHandle it gracefully, log at warn if usefulLog at error with the stack, alert someone, fix it

Later in this post, our custom error class marks operational errors with isOperational = true. Anything without that flag is treated as a bug: the client gets a generic message and the log gets the full details.

try/catch: Synchronous vs Asynchronous Code

try/catch lets you capture an error instead of letting it crash the program. The code inside try runs; if anything throws, execution jumps straight to catch with the error object, and the program continues after the block. That works perfectly for synchronous code, as in the TypeError example above.

The catch (pun intended) is that try/catch only sees errors thrown while the try block is running. A callback that runs later, such as a setTimeout callback or an old-style Node.js callback, runs after the try block is long finished, so the outer catch never sees its error. The fix is to put the try/catch inside the callback, or better, use promises with await.

try {
  setTimeout(() => {
    JSON.parse('{oops'); // throws later, outside the try block
  }, 0);
} catch (e) {
  console.log('outer catch never runs');
}
// The process crashes with:
// SyntaxError: Expected property name or '}' in JSON at position 1 (line 1 column 2)

With promises, the rule is simple: try/catch catches a rejected promise only if you await it. Forget the await and the function finishes happily, then the promise rejects with nobody listening. Since Node.js 15, an unhandled rejection crashes the whole process by default.

function findProduct(id) {
  return new Promise((resolve, reject) => {
    setTimeout(() => reject(new Error(`Product ${id} not found`)), 10);
  });
}

function getProduct() {
  try {
    findProduct(7); // no await
  } catch (e) {
    console.log('never runs');
  }
  console.log('getProduct finished, nothing caught');
}
getProduct();

// getProduct finished, nothing caught
// Error: Product 7 not found
//     at Timeout._onTimeout (...\nocatch.js:3:29)
// Node.js v24.22.2       (process exits with code 1)

async function withAwait() {
  try {
    await findProduct(42);
  } catch (e) {
    console.log('caught with await:', e.message); // caught with await: Product 42 not found
  }
}

If you are not comfortable with promises yet, the Promises and Async Await chapter covers them step by step.

The Error Object: message, name, stack and cause

When JavaScript hits a problem, it creates an Error object, and you can create your own with new Error('...'). The object carries everything you need to debug: message (what went wrong, in words), name (the kind of error, such as TypeError or SyntaxError), and stack (the chain of function calls that led there, with file names and line numbers). The stack is exactly what was missing from Imran's log.

try {
  throw new Error('Inventory not found');
} catch (error) {
  console.log(error.name);    // Error
  console.log(error.message); // Inventory not found
  console.log(error.stack.split('\n').slice(0, 2).join('\n'));
  // Error: Inventory not found
  //     at Object.<anonymous> (...\basics.js:13:9)
}

Since ES2022, errors can also carry a cause. This is useful when you catch a low-level error and throw a clearer one: you keep the human-friendly message without losing the original technical reason.

function loadOrder(id) {
  try {
    JSON.parse('{bad json');
  } catch (err) {
    throw new Error(`Could not load order ${id}`, { cause: err });
  }
}

try {
  loadOrder('ORD-1001');
} catch (err) {
  console.log(err.message);                          // Could not load order ORD-1001
  console.log(err.cause.name, '-', err.cause.message);
  // SyntaxError - Expected property name or '}' in JSON at position 1 (line 1 column 2)
}

One rule follows from this: always throw Error objects, never plain strings. throw 'oops' is legal JavaScript, but the value you catch is just a string with no stack at all (typeof e is 'string' and e.stack is undefined), so your logs lose the most important clue.

A Custom AppError Class with a Status Code

Throwing new Error('Vendor account inactive') gives you a message, but an API also needs to know which HTTP status to send and a stable code the front end can check. A small class that extends Error carries all of that in one object.

// errors/AppError.js
class AppError extends Error {
  constructor(message, statusCode = 500, code = 'INTERNAL_ERROR', details) {
    super(message);
    this.name = 'AppError';
    this.statusCode = statusCode;
    this.code = code;
    this.details = details;
    this.isOperational = true; // an expected problem, not a bug
  }
}
module.exports = AppError;

const err = new AppError('Product not found', 404, 'PRODUCT_NOT_FOUND');
console.log(err instanceof AppError, err instanceof Error); // true true
console.log(err.name, err.statusCode, err.code, err.isOperational);
// AppError 404 PRODUCT_NOT_FOUND true
console.log(String(err)); // AppError: Product not found

Because it extends Error, an AppError still has a stack trace and works with instanceof. Now a route can say throw new AppError('Seller account inactive', 403, 'SELLER_INACTIVE') and stop worrying about how the response is built. The code field matters more than it looks: messages get reworded or translated into Hindi, but the front end can keep checking PRODUCT_NOT_FOUND forever.

Express Default Error Handling

Express already catches errors thrown inside route handlers and sends a response, so the server does not crash. To see what it does on its own, here is a route that throws, with no error handling of ours, tested with fetch:

const express = require('express');
const app = express();

app.get('/crash', (req, res) => {
  throw new Error('Server Error');
});
app.listen(3141);

// Development (NODE_ENV not set):
// 500 text/html; charset=utf-8
// <pre>Error: Server Error<br> &nbsp; &nbsp;at ...\default.js:4:9<br> ...  (full stack trace in the page)

// NODE_ENV=production:
// 500 text/html; charset=utf-8
// <pre>Internal Server Error</pre>

// Unknown route, both modes:
// 404 ... <pre>Cannot GET /nope</pre>

Three things are wrong with this for an API. The response is HTML, while your mobile app or React front end expects JSON. In development it sends the full stack trace, with file paths from the server, to whoever made the request, so forgetting to set NODE_ENV=production on a server leaks your internals. And every failure looks the same, so the client cannot tell "product not found" from "database down". Express also prints the stack to stderr, but with no request id or URL next to it. The fix is to write our own error middleware.

Centralised Error Handling in Express

Beginners often wrap every route in its own try/catch and build a slightly different error response in each one. After twenty routes, the API returns {"error": "Oops"} in one place and {"msg": "failed"} in another, some errors are logged and some are not, and changing the format means editing every file. Centralised error handling means routes only raise errors; one middleware at the end decides the status code, the JSON body and what to log. Think of it as a single complaints desk: every problem in the building ends up there, and that desk alone decides the reply.

Error Middleware Has Four Arguments

Express recognises error-handling middleware by its four parameters: (err, req, res, next). A normal middleware has three. Even if you never use next inside it, you must declare it, because Express counts the parameters (the function's length) to decide which kind it is. With only three, Express treats it as a normal middleware and skips it when an error is passed along.

app.use((err, req, res, next) => {
  res.status(err.statusCode ?? 500).json({ success: false, message: err.message });
});

Error middleware must be registered after all your routes, because Express runs middleware in the order you add it.

Passing Errors On with next(err)

When something goes wrong in a route or middleware, you hand the error to Express with next(err). Calling next with any argument (except the special strings 'route' and 'router') tells Express "this request failed": it skips every remaining normal middleware and route and jumps to the first error middleware. Inside a synchronous route you can also simply throw; Express catches it and does the same thing.

app.get('/admin/reports', (req, res, next) => {
  const role = req.get('X-Demo-Role'); // stand-in for a verified JWT
  if (!role) return next(new AppError('Login required', 401, 'UNAUTHENTICATED'));
  if (role !== 'admin') return next(new AppError('You do not have permission', 403, 'FORBIDDEN'));
  res.json({ success: true, data: [] });
});

Notice the return before next(...). Without it, the function continues and tries to send a second response, which fails with ERR_HTTP_HEADERS_SENT.

A Standard JSON Error Shape

Front-end developers should be able to write one piece of code that handles every error from your API. That only works if every error has the same shape. Compare:

// Bad: different in every route, nothing to check in code
{ "error": "Oops" }

// Better: consistent, machine-readable code, traceable request id
{
  "success": false,
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Product not found",
    "requestId": "791966ee-d97c-44eb-8a43-19ec65bafcf1"
  }
}

// Validation errors add field-level details
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      { "field": "name", "message": "Name is required" },
      { "field": "price", "message": "Price must be a number greater than 0" }
    ],
    "requestId": "e67c6dad-3060-4bf2-bf79-7d1916a9c4e8"
  }
}

The requestId is the piece Imran was missing. When a customer sends a screenshot of an error, the support team can search the logs for that id and find the exact request, its stack trace and everything logged along the way. There are public standards for this shape too, such as RFC 9457 "Problem Details" (application/problem+json); whichever you pick, use it everywhere.

Handling 404s

There are two different "not found" cases. A missing resource is a valid route with an unknown id, like GET /products/99; the route itself throws new AppError('Product not found', 404, 'PRODUCT_NOT_FOUND'). A missing route is a URL your app does not have at all, like /api/orderz. Express ends up at its own HTML "Cannot GET" page for those, so add a catch-all middleware after the routes that turns them into a normal error:

function notFound(req, res, next) {
  next(new AppError(`Route ${req.method} ${req.originalUrl} not found`, 404, 'ROUTE_NOT_FOUND'));
}

Because it calls next(err) instead of answering directly, the 404 also goes through the central handler, so it gets the same JSON shape, the request id and a log line.

The Complete Error Handler

Here is the full middleware used in the rest of this post. It converts errors from libraries (the JSON body parser, multer) into AppErrors, picks the status code, logs 4xx at warn and 5xx at error with the stack, and hides internal messages and stack traces in production. The logger it imports is the winston logger built in the logging section below.

// middleware/errorHandler.js
const multer = require('multer');
const logger = require('../logger');
const AppError = require('../errors/AppError');

function notFound(req, res, next) {
  next(new AppError(`Route ${req.method} ${req.originalUrl} not found`, 404, 'ROUTE_NOT_FOUND'));
}

// Turn errors from libraries into AppErrors with a clear status and code
function normalise(err) {
  if (err instanceof AppError) return err;
  if (err.type === 'entity.parse.failed') {
    return new AppError('Request body is not valid JSON', 400, 'INVALID_JSON');
  }
  if (err.type === 'entity.too.large') {
    return new AppError('Request body is too large', 413, 'PAYLOAD_TOO_LARGE');
  }
  if (err instanceof multer.MulterError) {
    if (err.code === 'LIMIT_FILE_SIZE') {
      return new AppError('File is too large. Maximum size is 2 MB', 413, 'FILE_TOO_LARGE');
    }
    return new AppError(err.message, 400, err.code); // e.g. LIMIT_UNEXPECTED_FILE
  }
  return err; // unknown error: treated as a 500 below
}

function errorHandler(err, req, res, next) {
  if (res.headersSent) return next(err); // too late for JSON; let Express close the connection

  const appErr = normalise(err);
  const status = appErr.statusCode ?? 500;
  const isServerError = status >= 500;
  const isProd = process.env.NODE_ENV === 'production';

  logger.log(isServerError ? 'error' : 'warn', err.message, {
    requestId: req.id,
    method: req.method,
    url: req.originalUrl,
    status,
    code: appErr.code,
    stack: isServerError ? err.stack : undefined,
  });

  res.status(status).json({
    success: false,
    error: {
      code: appErr.code ?? 'INTERNAL_ERROR',
      message: isServerError && isProd ? 'Something went wrong. Please try again.' : appErr.message,
      details: appErr.details,
      requestId: req.id,
      ...(isProd ? {} : { stack: err.stack }),
    },
  });
}
module.exports = { notFound, errorHandler };

The res.headersSent check handles a rare case: if the error happens after the response has started streaming, you cannot send a new status code, so you pass the error to Express's default handler, which closes the connection. The err.type checks are needed because express.json() reports a broken body or an oversized body with its own error objects (with type values 'entity.parse.failed' and 'entity.too.large').

And here is the app that uses it. The request id and morgan middleware are explained in the logging section; for now, focus on how routes simply throw and the handler does the rest.

// app.js
const express = require('express');
const morgan = require('morgan');
const logger = require('./logger');
const AppError = require('./errors/AppError');
const requestId = require('./middleware/requestId');
const { validateProduct } = require('./middleware/validate');
const { notFound, errorHandler } = require('./middleware/errorHandler');

const app = express();
app.use(requestId);
morgan.token('id', (req) => req.id);
app.use(morgan(':id :method :url :status :response-time ms', {
  stream: { write: (line) => logger.http(line.trim()) },
}));
app.use(express.json({ limit: '10kb' }));

const products = new Map([[1, { id: 1, name: 'Blue pottery vase', price: 1499, quantity: 12 }]]);
const db = { findOrders: async () => { throw new Error('connect ECONNREFUSED 127.0.0.1:3306'); } };

app.get('/products/:id', (req, res) => {
  const id = Number(req.params.id);
  if (!Number.isInteger(id)) throw new AppError('Product id must be a number', 400, 'INVALID_ID');
  const product = products.get(id);
  if (!product) throw new AppError('Product not found', 404, 'PRODUCT_NOT_FOUND');
  res.json({ success: true, data: product });
});

app.post('/products', validateProduct, (req, res) => {
  const id = products.size + 1;
  const product = { id, ...req.body };
  products.set(id, product);
  logger.info('product created', { requestId: req.id, productId: id });
  res.status(201).json({ success: true, data: product });
});

app.get('/orders', async (req, res) => {
  const orders = await db.findOrders(); // rejects: Express 5 forwards it to errorHandler
  res.json({ success: true, data: orders });
});

// ... the /admin/reports route shown earlier ...

app.get('/bug', (req, res) => {
  res.json({ total: cart.total }); // programmer error: cart is not defined
});

app.use(notFound);
app.use(errorHandler);
module.exports = app;

A test script started this app on port 3143, called each route with fetch, printed the status and body, and closed the server. These are the real responses with NODE_ENV=production (request ids differ on every run):

found:       200 {"success":true,"data":{"id":1,"name":"Blue pottery vase","price":1499,"quantity":12}}
missing:     404 {"success":false,"error":{"code":"PRODUCT_NOT_FOUND","message":"Product not found","requestId":"ddcaea11-..."}}
bad id:      400 {"success":false,"error":{"code":"INVALID_ID","message":"Product id must be a number","requestId":"cfef0c85-..."}}
create ok:   201 {"success":true,"data":{"id":2,"name":"Leather mojari","price":899,"quantity":5}}
broken json: 400 {"success":false,"error":{"code":"INVALID_JSON","message":"Request body is not valid JSON","requestId":"8fd50475-..."}}
too big:     413 {"success":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body is too large","requestId":"d7a95a47-..."}}
async db:    500 {"success":false,"error":{"code":"INTERNAL_ERROR","message":"Something went wrong. Please try again.","requestId":"35512abf-..."}}
no token:    401 {"success":false,"error":{"code":"UNAUTHENTICATED","message":"Login required","requestId":"1f6f5f26-..."}}
not admin:   403 {"success":false,"error":{"code":"FORBIDDEN","message":"You do not have permission","requestId":"38bbd480-..."}}
bug:         500 {"success":false,"error":{"code":"INTERNAL_ERROR","message":"Something went wrong. Please try again.","requestId":"0ab5ff95-..."}}
no route:    404 {"success":false,"error":{"code":"ROUTE_NOT_FOUND","message":"Route GET /does-not-exist not found","requestId":"6eb0d345-..."}}

Every failure has the right status, the same shape and a request id. The two 500s (the database outage and the ReferenceError bug) tell the client nothing about MySQL, ports or variable names, while the log keeps the full story, as you will see in the logging section.

Async Errors: Express 5 vs Express 4

Most real routes are async because they wait for a database. What happens when the awaited promise rejects depends on your Express version, and many older tutorials (including the original version of this post) are written for Express 4.

Express 5 (the current major version, 5.3.0 in this test) checks whether a route or middleware returns a promise. If that promise rejects, Express calls next(err) for you. That is why the /orders route above needs no try/catch: the rejected findOrders() goes straight to the error handler.

Express 4 ignores the returned promise. The rejection is unhandled, the client never gets a response, and with Node.js's default behaviour the whole process crashes. The usual Express 4 fix is a small wrapper, often called asyncHandler, that catches the rejection and passes it to next:

const asyncHandler = (fn) => (req, res, next) =>
  Promise.resolve(fn(req, res, next)).catch(next);

app.get('/vendors', async (req, res) => {          // plain async route
  const vendors = await findVendors();              // rejects: 'DB connection lost'
  res.json(vendors);
});

app.get('/vendors-wrapped', asyncHandler(async (req, res) => {
  const vendors = await findVendors();
  res.json(vendors);
}));

The same file was run against both versions (Express 4 installed under an npm alias), with a one-second client timeout:

express 5.3.0
/vendors          500 {"success":false,"message":"DB connection lost"}
/vendors-wrapped  500 {"success":false,"message":"DB connection lost"}

express4 4.22.3   (with a process 'unhandledRejection' listener that only logs)
unhandledRejection: DB connection lost
/vendors          no response: TimeoutError
/vendors-wrapped  500 {"success":false,"message":"DB connection lost"}

express4 4.22.3   (without that listener)
Error: DB connection lost
Node.js v24.22.2     (the whole server exits with code 1)

That last case is a likely explanation for nights like Imran's: one rejected promise in one async route of an Express 4 app takes down the server for every customer. If you are on Express 4, wrap every async route (or use a package that patches the router), or better, upgrade to Express 5. On Express 5 the wrapper is harmless but unnecessary. You still need try/catch in Express 5 when you want to do something with the error, such as retrying, converting a database "duplicate key" error into a 409, or adding a cause.

Express 5 also changed req.body: when no body parser ran (for example, a GET request), req.body is undefined instead of {}. That is why the validation middleware below starts with req.body ?? {}. The Express.js Complete Guide covers middleware order and the request lifecycle in more detail.

Never Leak Stack Traces in Production

A stack trace shows file paths, folder names, library names and versions, and sometimes parts of SQL queries or connection strings. To an attacker, that is a map of your server. The original post's example of a bad message, "SQL connection failed at port 3306", is exactly this kind of leak: it tells the world you run MySQL on the default port.

Our handler follows three rules. For 4xx errors, the message is safe and useful to the client ("Product not found"), so it is sent as is. For 5xx errors in production, the client gets only "Something went wrong. Please try again." plus the request id, while the real message and stack go to the log. The stack field is only added outside production, which makes local debugging comfortable. The decision depends on NODE_ENV, so make sure your deployment really sets NODE_ENV=production; Express's own default handler also uses it, as the earlier test showed.

The Last Safety Net: unhandledRejection and uncaughtException

Some errors happen outside any request: a timer callback throws, a background job's promise rejects, a library emits an error nobody listens for. Express cannot catch these. Node.js offers two process-level events for them: 'unhandledRejection' (a promise rejected and nobody handled it) and 'uncaughtException' (a synchronous throw reached the top of the call stack).

The right use of these events is to log and exit, not to keep running. After an unexpected exception, the program may be in a broken state: half-finished database work, a lock never released, a counter wrong. The Node.js documentation says plainly that it is not safe to resume after 'uncaughtException'. Instead, log the error with its stack, exit with a failure code, and let a process manager such as PM2, systemd, Docker's restart policy or Kubernetes start a fresh process in a second or two.

// process-handlers.js (require this first in server.js)
const logger = require('./logger');

function crash(kind, err) {
  logger.error(`${kind}: ${err?.message ?? err}`, { stack: err?.stack });
  process.exitCode = 1;                              // exit as a failure...
  setTimeout(() => process.exit(1), 500).unref();    // ...even if a server keeps the loop alive
}
process.on('unhandledRejection', (reason) => crash('unhandledRejection', reason));
process.on('uncaughtException', (err) => crash('uncaughtException', err));

Promise.reject(new Error('Payment gateway timed out'));

// {"level":"error","message":"unhandledRejection: Payment gateway timed out","service":"shop-api",
//  "stack":"Error: Payment gateway timed out\n    at Object.<anonymous> (...)","timestamp":"2026-11-02T08:37:45.019Z"}
// exit code: 1

A detail worth knowing: the first version of this test only called setTimeout(() => process.exit(1), 200).unref(), and the script exited with code 0. Once you add a listener, Node.js no longer treats the error as fatal; with nothing else keeping the event loop alive, the process simply ran out of work and ended "successfully" before the unref'd timer fired. A process manager would then think the app stopped normally. Setting process.exitCode = 1 fixes that, and the timer covers the case where an open server keeps the process alive (tested with a live HTTP server: exit code 1). The short delay gives the log a moment to be written. In a real server you would also call server.close() first, as shown in the graceful shutdown section of the Node.js HTTP Module post.

HTTP Status Codes for Errors

Choosing the right status code is part of your API's contract. Clients, proxies, monitoring tools and retry logic all read it before they read the body. A common beginner mistake is returning 500 for everything, or 200 with {"success": false}, which makes every dashboard show "all fine" during an outage.

CodeMeaningUse it when
400 Bad RequestThe client sent something invalidValidation failed, invalid JSON, id is not a number
401 UnauthorizedNot authenticatedMissing, invalid or expired token; wrong password
403 ForbiddenAuthenticated but not allowedA seller opens admin reports, edits another seller's product
404 Not FoundResource or route does not existUnknown product id, unknown URL
409 ConflictRequest clashes with current stateEmail already registered, duplicate order number
413 Content Too LargeBody or file is over the limitJSON over 10 KB, image over 2 MB
415 Unsupported Media TypeWrong Content-TypeXML sent to a JSON-only endpoint
422 Unprocessable ContentWell-formed but semantically invalidSome teams use it for validation errors instead of 400; pick one and stay consistent
429 Too Many RequestsRate limit hitToo many OTP or login attempts
500 Internal Server ErrorUnexpected server failureBugs and unknown errors
502 / 503 / 504Upstream or availability problemPayment gateway down (502), maintenance or database unavailable (503), upstream timeout (504)

The newer names "Content Too Large" and "Unprocessable Content" come from RFC 9110; you will still see the older names "Payload Too Large" and "Unprocessable Entity" in many tools. The number is what matters.

Logging: The Diary of Your Backend

Logging means recording important events inside your application so you can understand later what happened, when, and to whom. A shopping mall installs security cameras not because something bad happens every day, but because when it does, the management needs evidence. Logs are the same: when a customer says "my order disappeared" or "I was charged twice", you need facts, not guesses. Good logs help you debug, monitor the health of the app, notice attacks, find slow endpoints and audit changes.

Back to Imran. A good log line for his crash would have answered his three questions at once: what happened (message and stack), when (timestamp), and which request (method, URL, request id, user id). Here is his old pattern next to a better one, both run:

// Before: the error is swallowed and the reason is lost
try {
  await placeOrder(order);
} catch (err) {
  console.log('something went wrong');
}
// something went wrong

// After: structured, searchable, and the error still reaches the central handler
try {
  await placeOrder(order);
} catch (err) {
  logger.error('order placement failed', { requestId: req.id, orderId: order.id, error: err.message, stack: err.stack });
  throw err;
}
// {"error":"Cannot read properties of undefined (reading 'length')","level":"error",
//  "message":"order placement failed","orderId":"ORD-1001",
//  "requestId":"3f0c9a7e-5b1d-4c39-9d4e-2a6b8f1e7c55","service":"shop-api",
//  "stack":"TypeError: Cannot read properties of undefined (reading 'length')\n    at placeOrder (...)", ...}

If you do nothing useful with an error in a catch block, it is usually better not to catch it at all. With the central handler in place, an uncaught error in a route is logged once, with the request id, and answered correctly.

What to Log, and What Never to Log

Logging nothing leaves you blind; logging everything buries the useful lines and costs money in storage. Log events that you would want to read during an investigation.

Log theseNever log these
Server start and shutdown, with version and portPasswords, even wrong ones (users often type their real password into the wrong field)
Every request: method, URL, status, response time, request idAccess tokens, refresh tokens, session ids, API keys, JWT secrets, private keys
Login success and failure, password reset requested, OTP or MFA failure (user id, IP)OTP codes
Authorization failures (who tried to reach what)Full card numbers or CVV (at most the last four digits)
Business events: order created, payment succeeded or failed, refund issuedAadhaar numbers, PAN, bank account numbers (mask them if you must reference them)
Database and third-party failures, slow responses, unexpected errors with stackFull request bodies by default (they may contain any of the above)

Logs are copied to many places: log files, monitoring services, developer laptops during an investigation. A password or Aadhaar number in a log is a data leak waiting to happen, and in India the Digital Personal Data Protection Act, 2023 makes careless handling of personal data a legal risk as well as a security one. The safest approach is to make secrets impossible to log by accident, with a redaction step in the logger itself, shown below.

Log Levels

Not every log line is equally important. Levels let you label each line and then choose, per environment, how much detail to keep. Winston uses the npm levels; a lower number means more serious:

console.log(require('winston').config.npm.levels);
// { error: 0, warn: 1, info: 2, http: 3, verbose: 4, debug: 5, silly: 6 }
LevelMeaningExample
errorSomething failed and may need attention nowDatabase connection failed, payment gateway timeout, unhandled bug
warnUnusual but handled; worth a look if it repeatsProduct uploaded without an image, validation failures, 403s
infoNormal, important business eventsServer started, seller logged in, order created
httpOne line per requestMorgan's request lines
debugDetail for developmentRequest payload received, cache hit or miss

When you set level: 'info', winston keeps info and everything more serious (warn, error) and drops http, debug and the rest. Production usually runs at info or http; you lower it to debug temporarily while investigating.

Why console.log Is Not Enough

console.log is perfect while learning. In a real API it falls short in several ways. It has no levels, so you cannot turn off debug noise in production or filter only errors. It has no timestamp or request context, so lines from hundreds of parallel requests interleave and you cannot tell which belong together. It prints free text, so searching "all failed payments for ORD-1001" means fragile text searches. And it writes only to the terminal; when the process restarts, whatever was on screen is gone unless something else captured it. A logging library fixes all four.

Request Logging with morgan

Morgan is an Express middleware that writes one line per request: method, URL, status, response size and time. Install it with npm install morgan and add it near the top of your app. It writes the line when the response finishes, so it knows the final status. Here are the three most used formats, captured from the same three requests:

const morgan = require('morgan');
app.use(morgan('tiny'));   // or 'combined', or 'dev'

// --- morgan('tiny'): method url status bytes - time
GET /products 200 10 - 1.853 ms
POST /orders 201 17 - 0.442 ms
GET /missing 404 146 - 1.188 ms

// --- morgan('combined'): Apache "combined" format with IP, date, protocol, referrer, user agent
::1 - - [02/Nov/2026:08:37:18 +0000] "GET /products HTTP/1.1" 200 10 "-" "demo-client/1.0"
::1 - - [02/Nov/2026:08:37:18 +0000] "POST /orders HTTP/1.1" 201 17 "-" "node"
::1 - - [02/Nov/2026:08:37:18 +0000] "GET /missing HTTP/1.1" 404 146 "-" "node"

// --- morgan('dev'): short, status coloured (green 2xx, cyan 3xx, yellow 4xx, red 5xx)
GET /products 200 0.329 ms - 10
POST /orders 201 0.269 ms - 17
GET /missing 404 0.213 ms - 146

dev is pleasant in a terminal, but its colour codes become junk characters in a file. combined is a standard format that many log tools can parse, which makes it a common production choice. You can also define your own format with tokens, as our app.js does with ':id :method :url :status :response-time ms', and send morgan's output into winston through the stream option so request lines and application logs end up in the same place.

Morgan only knows about HTTP requests. It cannot record that a payment failed, that a seller logged in, or the stack trace of an error. For that you need an application logger.

Application Logging with winston

Winston (npm install winston) is a widely used logging library for Node.js. If morgan is the receptionist who notes every visitor, winston is the records department that keeps every kind of file. The smallest useful logger has a level and a console transport (a destination for log lines):

const winston = require('winston');
const logger = winston.createLogger({
  level: 'info',
  format: winston.format.simple(),
  transports: [new winston.transports.Console()],
});

logger.info('Order created');            // info: Order created
logger.warn('Inventory low');            // warn: Inventory low
logger.error('Database failed');         // error: Database failed
logger.debug('Request payload received'); // (nothing: debug is below 'info')

For production, three changes make logs far more useful: JSON format, so every field is searchable; file transports (or a log shipper), so logs survive restarts; and redaction, so secrets cannot slip in. This is the logger.js used by the app in this post:

// logger.js
const winston = require('winston');
const { combine, timestamp, errors, json } = winston.format;

const SECRET_KEYS = ['password', 'token', 'authorization', 'cardNumber', 'aadhaar', 'otp'];
const redact = winston.format((info) => {
  for (const key of SECRET_KEYS) {
    if (info[key] !== undefined) info[key] = '[REDACTED]';
  }
  return info;
});

const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: combine(redact(), timestamp(), errors({ stack: true }), json()),
  defaultMeta: { service: 'shop-api' },
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: 'logs/error.log', level: 'error' }),
    new winston.transports.File({ filename: 'logs/combined.log' }),
  ],
});
module.exports = logger;

logger.info('login success', { userId: 42, password: 'hunter2', token: 'eyJhbGciOi...' });
// {"level":"info","message":"login success","password":"[REDACTED]","service":"shop-api",
//  "timestamp":"2026-11-02T08:37:18.929Z","token":"[REDACTED]","userId":42}

logger.error('payment failed', { orderId: 'ORD-1001', cardNumber: '4111111111111111', reason: 'gateway timeout' });
// {"cardNumber":"[REDACTED]","level":"error","message":"payment failed","orderId":"ORD-1001",
//  "reason":"gateway timeout","service":"shop-api","timestamp":"2026-11-02T08:37:18.930Z"}

logger.error(new Error('Database connection lost'));
// {"level":"error","message":"Database connection lost","service":"shop-api",
//  "stack":"Error: Database connection lost\n    at Object.<anonymous> (...)", "timestamp":"..."}

The two file transports split the logs: error.log receives only error lines, which is the first file to open during an incident, and combined.log receives everything at the logger's level. Log files grow quickly, especially with stack traces, which is why real deployments rotate files daily (for example with the winston-daily-rotate-file transport) or, more commonly in containers, log only to the console and let the platform collect the output. The errors({ stack: true }) format makes sure an Error object keeps its stack in the output instead of being reduced to its message.

Compare a vague line with a structured one. logger.error('Error') tells you nothing. logger.error('Database timeout while fetching products') is readable. logger.error('order failed', { module: 'orders', orderId: 'ORD-1001', error: err.message }) is readable and searchable: a log tool can show every line where orderId is ORD-1001, which lets you rebuild the whole journey of an order from creation to payment to delivery.

Request IDs: Connecting Every Line of One Request

A busy API handles many requests at the same moment, so their log lines interleave. A request id is a unique value attached to each request and added to every log line and error response for it. Search for the id, and you see exactly that request's story in order.

// middleware/requestId.js
const { randomUUID } = require('node:crypto');

module.exports = function requestId(req, res, next) {
  const incoming = req.get('X-Request-Id');
  req.id = incoming && /^[\w-]{8,64}$/.test(incoming) ? incoming : randomUUID();
  res.set('X-Request-Id', req.id);
  next();
};

If a load balancer or another service already sent an X-Request-Id, we reuse it (after checking it looks sane, since headers come from outside), so one id can follow a request across several services. Here are three real lines from the development run for the failing GET /products/99 request: the warning from the error handler and the request line from morgan share the same id, and the client's error body carried it too.

{"code":"PRODUCT_NOT_FOUND","level":"warn","message":"Product not found","method":"GET",
 "requestId":"f891ff5a-bdf2-43b1-992a-a3af5b06b915","service":"shop-api","status":404,
 "timestamp":"2026-11-02T08:36:32.705Z","url":"/products/99"}
{"level":"http","message":"f891ff5a-bdf2-43b1-992a-a3af5b06b915 GET /products/99 404 1.752 ms",
 "service":"shop-api","timestamp":"2026-11-02T08:36:32.706Z"}

{"level":"error","message":"connect ECONNREFUSED 127.0.0.1:3306","method":"GET",
 "requestId":"a8adf03e-d116-44cc-b96a-f1b9db4edede","service":"shop-api",
 "stack":"Error: connect ECONNREFUSED 127.0.0.1:3306\n    at Object.findOrders (...app.js:18:46)\n ...", ...}

The client was told only "Something went wrong" for the database error, but the log has the real cause and the exact line. That is the balance you want.

Logging Authentication and Authorization Events

Security-related events deserve their own log lines, because they are how you spot attacks. Log login success and failure, password reset requests, OTP or MFA failures, token refresh failures and account lockouts, each with the user id (or the attempted email), IP address, user agent and request id, but never the password, OTP or token itself. Authorization failures matter too: a seller account repeatedly trying to open admin URLs could be a bug in your front end, a misconfigured role, or someone probing for weaknesses. Log them at warn so they are easy to count. Fifty failed logins for one account in a minute, or failed logins for hundreds of accounts from one IP, are patterns a monitoring alert can catch.

Monitoring and Centralised Logs

Once you run more than one server, or containers that come and go, log files on each machine are not practical. Logs are shipped to a central service where you can search across all servers, build dashboards and set alerts. Common options include AWS CloudWatch Logs, the Elastic Stack (Elasticsearch, Logstash, Kibana), Grafana Loki, Datadog and Splunk; which one fits depends mostly on where you host and your budget. On AWS, for example, logs written to the console by a container or Lambda function can be collected into CloudWatch Logs, where you can search them and create alarms such as "more than 20 error lines in 5 minutes". JSON logs with consistent field names make all of these tools far more useful.

Logs also reveal performance problems. If morgan's response time for GET /products is usually around 50 ms and suddenly sits at 3,000 ms, a dashboard on that field shows the change before customers start complaining.

Validation: Never Trust User Input

Imagine a warehouse that accepts every package without checking it. Soon it holds boxes with a quantity of -50, a price of -100, no product name, and a contact email of "abc". A good warehouse inspects goods at the receiving door. A good backend checks every incoming request at the door too, before the data reaches business logic or the database. That check is validation: making sure incoming data follows the expected rules. Without it, bad data causes crashes, wrong reports, corrupted records and security holes.

Frontend Validation vs Backend Validation

A common belief is "the form already checks it, so the backend does not need to". This is wrong. Anyone can call your API directly with curl, Postman or a script and send {"price": -100}, skipping your form entirely. Frontend validation exists for user experience; backend validation exists for security and correctness.

Frontend validationBackend validation
PurposeInstant feedback ("Please enter your email")Security and data integrity
Can it be bypassed?Yes, easilyNo, every request passes through it
Required?RecommendedMandatory

Validate everything that comes from outside: the body, route parameters (/products/abc when the id should be a number), query strings, headers you rely on and uploaded files. Internal APIs are not an exception; a bug in another service can send bad data just as easily as an attacker.

A Validation Middleware

Validation fits naturally into middleware: it runs after the body is parsed and before the route handler, so bad requests never reach your business code or database. Typical rules are required fields, formats (email, PIN code), minimum and maximum lengths, numeric types and ranges. Here is a hand-written validator for creating a product, which collects all problems at once instead of stopping at the first one:

// middleware/validate.js
const AppError = require('../errors/AppError');

function validateProduct(req, res, next) {
  const { name, price, quantity } = req.body ?? {};
  const errors = [];

  if (typeof name !== 'string' || name.trim() === '') {
    errors.push({ field: 'name', message: 'Name is required' });
  } else if (name.length > 100) {
    errors.push({ field: 'name', message: 'Name must be at most 100 characters' });
  }
  if (typeof price !== 'number' || !Number.isFinite(price) || price <= 0) {
    errors.push({ field: 'price', message: 'Price must be a number greater than 0' });
  }
  if (!Number.isInteger(quantity) || quantity < 0) {
    errors.push({ field: 'quantity', message: 'Quantity must be a whole number, 0 or more' });
  }

  if (errors.length) {
    return next(new AppError('Validation failed', 400, 'VALIDATION_ERROR', errors));
  }
  next();
}
module.exports = { validateProduct };

// POST /products  {"name":"","price":-500,"quantity":"hello"}
// 400 {"success":false,"error":{"code":"VALIDATION_ERROR","message":"Validation failed",
//      "details":[{"field":"name","message":"Name is required"},
//                 {"field":"price","message":"Price must be a number greater than 0"},
//                 {"field":"quantity","message":"Quantity must be a whole number, 0 or more"}],
//      "requestId":"e67c6dad-..."}}

Look at the typeof price !== 'number' check. The original version of this middleware only checked if (price <= 0), and in JavaScript "hello" <= 0 is false, so the string "hello" would have passed as a valid price. The same goes for a missing price: undefined <= 0 is also false. Type checks must come before range checks.

Validation Libraries: Joi, express-validator and Zod

Hand-written checks work, but they grow long as forms grow. Validation libraries let you describe the rules as a schema and do the checking for you. Joi (npm install joi) is a long-standing choice:

const Joi = require('joi');

const productSchema = Joi.object({
  name: Joi.string().trim().max(100).required(),
  price: Joi.number().positive().required(),
  quantity: Joi.number().integer().min(0).required(),
  sellerEmail: Joi.string().email(),
});

const ok = productSchema.validate({ name: 'Bandhani dupatta', price: 650, quantity: 20 });
console.log(ok.error, ok.value);
// undefined { name: 'Bandhani dupatta', price: 650, quantity: 20 }

const bad = productSchema.validate(
  { name: '', price: -500, quantity: 'hello', sellerEmail: 'abc' },
  { abortEarly: false } // report all errors, not just the first
);
console.log(bad.error.details.map(d => ({ field: d.path.join('.'), message: d.message })));
// [ { field: 'name', message: '"name" is not allowed to be empty' },
//   { field: 'price', message: '"price" must be a positive number' },
//   { field: 'quantity', message: '"quantity" must be a number' },
//   { field: 'sellerEmail', message: '"sellerEmail" must be a valid email' } ]

console.log(productSchema.validate({ name: 'Lamp', price: '799', quantity: 2 }).value);
// { name: 'Lamp', price: 799, quantity: 2 }   (the string '799' was converted to a number)

console.log(productSchema.validate({ name: 'Lamp', price: 799, quantity: 2, isAdmin: true }).error.message);
// "isAdmin" is not allowed

Two behaviours are worth knowing. Joi converts types by default, so '799' becomes 799; use the returned value, not the original req.body, or pass { convert: false } if you want strict types. And unknown keys are rejected by default, which protects you from a client quietly sending isAdmin: true. To use a schema as middleware, wrap it the same way as validateProduct: validate, and on error call next(new AppError('Validation failed', 400, 'VALIDATION_ERROR', details)).

express-validator takes a different approach: you chain rules directly in the route, such as body('email').isEmail(), which suits small APIs with simple checks. Zod is popular in TypeScript projects because the same schema also gives you the type. All three are reasonable; the important part is that validation runs on the backend, early, and returns field-level messages. For larger projects, keep schemas in their own folder (for example src/validations/productSchema.js) rather than inside controllers. Business rules that need the database, such as "a seller must be at least 18 years old and have a verified GST number", belong in the service layer after basic validation passes.

File Uploads with multer

Modern apps do not only receive text. A handicraft shop needs product photos; seller onboarding needs a GST certificate, a PAN card copy, a cancelled cheque and a shop logo; job portals need resumes; and many apps need invoices and identity documents. A backend has to receive these files, check them, store them safely and remember where they are. File uploads are also one of the most abused features on the web, so every step needs care.

How a File Travels: multipart/form-data

APIs normally send JSON, but JSON is a poor way to carry binary files. Browsers and HTTP clients send files using multipart/form-data: the request body is split into parts separated by a boundary string, and each part holds either a text field (title = Blue pottery vase) or a file (with its file name and claimed content type). The journey is: the user picks a file, the client builds a multipart request, the server parses it, validates the file, stores it, saves the file's details in the database, and responds.

express.json() does not parse multipart bodies, so for uploads you need a parser. Multer (npm install multer) is the Express middleware maintained under the Express organisation for this job. Think of it as the receiving department in the warehouse: it accepts the delivery, checks it against your rules, names it, puts it on a shelf and hands your route a receipt in req.file.

single, array and fields

Multer gives you a middleware per route, depending on how many files you expect:

const upload = multer({ storage: multer.memoryStorage(), limits: { fileSize: 2 * 1024 * 1024 } });

// One file in the "image" field  -> req.file
app.post('/products/:id/image', upload.single('image'), handler);

// Up to 4 files in the "images" field  -> req.files (an array)
app.post('/products/7/images', upload.array('images', 4), (req, res) => {
  res.json({ count: req.files.length, names: req.files.map(f => f.originalname), body: req.body });
});
// 3 files  -> 200 {"count":3,"names":["front.jpg","back.jpg","side.jpg"],"body":{"title":"Blue pottery vase"}}
// 5 files  -> 400 {"code":"LIMIT_UNEXPECTED_FILE","message":"Unexpected file field","field":"images"}

// Different named fields  -> req.files is an object keyed by field name
app.post('/sellers/onboard', upload.fields([
  { name: 'gst_certificate', maxCount: 1 },
  { name: 'pan_card', maxCount: 1 },
  { name: 'shop_logo', maxCount: 1 },
]), (req, res) => {
  res.json({ fields: Object.keys(req.files), logo: req.files.shop_logo?.[0].originalname, shopName: req.body.shopName });
});
// 200 {"fields":["gst_certificate","pan_card","shop_logo"],"logo":"logo.png","shopName":"Marwar Crafts"}

Text fields sent in the same form, such as title or shopName, appear in req.body. Note that sending more files than maxCount gives the slightly confusing error LIMIT_UNEXPECTED_FILE, the same code you get when the field name is wrong.

Disk Storage vs Memory Storage

Multer can store an incoming file in two ways. diskStorage streams the file straight to a folder on the server's disk and gives you req.file.path; memory use stays low even for large files. memoryStorage keeps the whole file in RAM as req.file.buffer; that is convenient when you will immediately send it somewhere else, such as object storage, or inspect its bytes, but a few large uploads at the same time can use a lot of memory, so it must always be paired with a small fileSize limit.

diskStoragememoryStorage
Where the file goesA folder on the server (req.file.path)RAM (req.file.buffer)
Memory useLow, the file is streamed to diskThe full file size, per upload in progress
Good forLarge files, single-server apps, processing with other toolsSmall files you forward to S3 or check byte by byte
Watch out forFilling the disk; files lost when a container is replacedRunning out of memory without strict limits

Imran's Upload Endpoint and the 25 MB Photo

A few weeks after fixing his logging, Imran adds product photo uploads. His first version is the one from many tutorials: multer({ dest: 'uploads/' }) with no limits. A seller in Barmer photographs a new batch of camel-leather bags with a DSLR and uploads the originals. In a test with a 25 MB file, that endpoint happily answers 200 {"size":26214400,"path":"uploads\\1012c579ef144c306df1eaccc8fad6e0"}. The seller's connection is slow, so they retry again and again, and every attempt adds another 25 MB to the small server's disk. A few days later the disk is full, and every write on the server starts failing with ENOSPC: no space left on device, including the log files he had just set up. One missing option, limits.fileSize, turned a photo upload into an outage.

Limits are not optional. Besides fileSize (bytes per file), multer supports files (number of files), fields and fieldSize (text fields), and parts. With a limit in place, multer stops reading as soon as the file crosses it, deletes the partial file, and passes a MulterError with code LIMIT_FILE_SIZE to your error middleware. Our normalise() function turns that into a 413:

const { MulterError } = require('multer');
const e = new MulterError('LIMIT_FILE_SIZE', 'image');
console.log(e.name, e.code, e.message, e.field, e instanceof Error);
// MulterError LIMIT_FILE_SIZE File too large image true

Also keep your images reasonable after upload: a product listing does not need a 6000-pixel original. Compressing, resizing, generating thumbnails and converting to WEBP saves storage and bandwidth and makes pages load faster; these are usually done in a background job after the upload succeeds.

fileFilter: Check the Type, and Why mimetype Alone Can Be Spoofed

Never accept every file type. An image endpoint should not store setup.exe, a ZIP bomb or a script. Multer's fileFilter runs for each file before it is stored, and you call cb(null, true) to accept or pass an error to reject.

The trap is that file.mimetype is not detected by multer. It is simply the Content-Type the client wrote into that part of the request, and any script can write image/png on anything. The file name is also chosen by the client. So check both the claimed type and the extension against an allow-list, and treat that as a first filter, not proof:

const path = require('node:path');
const ALLOWED = {
  'image/jpeg': ['.jpg', '.jpeg'],
  'image/png': ['.png'],
  'image/webp': ['.webp'],
};

function fileFilter(req, file, cb) {
  const ext = path.extname(file.originalname).toLowerCase();
  const allowedExts = ALLOWED[file.mimetype];
  if (allowedExts && allowedExts.includes(ext)) return cb(null, true);
  cb(new AppError('Only JPG, PNG or WEBP images are allowed', 400, 'INVALID_FILE_TYPE'));
}

This blocks setup.exe sent as image/png, because the extension does not match. But a test that uploaded a small PHP script named photo.png with the type image/png passed the filter and was saved (201, 19 bytes), because both the claimed type and the extension looked right. To know what a file really is, read its first bytes, called the magic number or file signature: every PNG starts with the bytes 89 50 4E 47 0D 0A 1A 0A, every JPEG with FF D8 FF. With memory storage that check is short:

const upload = multer({ storage: multer.memoryStorage(), limits: { fileSize: 2 * 1024 * 1024 } });

function detectImageType(buf) {
  if (buf.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return 'image/png';
  if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return 'image/jpeg';
  if (buf.subarray(0, 4).toString('latin1') === 'RIFF' && buf.subarray(8, 12).toString('latin1') === 'WEBP') return 'image/webp';
  return null;
}

app.post('/avatar', upload.single('image'), async (req, res) => {
  if (!req.file) throw new AppError('Image is required', 400, 'FILE_REQUIRED');
  const realType = detectImageType(req.file.buffer);
  if (!realType) throw new AppError('File content is not a JPG, PNG or WEBP image', 400, 'INVALID_FILE_CONTENT');
  // here you would send req.file.buffer to object storage (for example S3) and save the URL
  res.status(201).json({ claimed: req.file.mimetype, detected: realType, bytes: req.file.size });
});

// real png             -> 201 {"claimed":"image/png","detected":"image/png","bytes":70}
// text renamed to .png -> 400 {"success":false,"error":{"code":"INVALID_FILE_CONTENT",
//                              "message":"File content is not a JPG, PNG or WEBP image","requestId":"ac42f169-..."}}

Packages such as file-type detect many more formats the same way. For sensitive systems, go further: re-encode images through an image library (which drops anything hidden inside them) and scan documents with an antivirus service before making them available.

Safe, Random File Names

Using file.originalname as the stored name, as the classic tutorial example does, causes two problems. Two sellers uploading logo.png overwrite each other. Worse, the name is attacker-controlled: names like ../../app.js, very long names, or names with odd characters can cause trouble in some setups. Prefixing Date.now() reduces collisions but still keeps the user's text. The safer pattern is to generate the whole name yourself with a random UUID and keep only a lower-cased, allow-listed extension. Store the original name in the database if you want to show it later.

const { randomUUID } = require('node:crypto');

const storage = multer.diskStorage({
  destination: UPLOAD_DIR,
  filename: (req, file, cb) => {
    const ext = path.extname(file.originalname).toLowerCase();
    cb(null, `${randomUUID()}${ext}`); // never trust the user's file name
  },
});
// originalname "vase.PNG"  ->  stored as "5b8231f8-8410-4171-836d-c70458f71ef3.png"

Because fileFilter runs before filename, the extension here has already been checked against the allow-list.

Where to Store Files: Outside the Web Root, or in Object Storage

Never save uploads inside a folder your server serves directly, such as public/. If someone manages to upload an HTML or SVG file with a script inside, and that folder is served as is, the script runs in your customers' browsers on your domain. Store files in a folder outside anything served by express.static (our example uses storage/product-images), and serve them through a route that sets the right Content-Type and checks permissions where needed.

Local disk is fine for learning and small single-server apps, but it does not scale: files disappear when a container is replaced, two servers do not share a disk, and backups are your problem. Storing files inside the database (for example as MySQL BLOBs) makes the database large and slow, so it is rarely a good idea for images. Most production systems use object storage, such as Amazon S3, Google Cloud Storage or Azure Blob Storage, and keep only the file's key or URL plus details (owner, size, type, original name) in the database. A common flow is: receive the file, validate type and size, generate a unique key, upload to S3, save the key and metadata in the database, and return the URL. For large files, many apps go one step further and give the client a short-lived pre-signed URL so the browser uploads directly to S3 without passing through the Node.js server at all.

Not every file should be public. Product images, shop logos and banners can be public, ideally served through a CDN. Seller documents such as the GST certificate, PAN card copy, cancelled cheque and bank statements are private: keep them in a private bucket and serve them only after checking that the logged-in user is allowed to see them, for example through a pre-signed URL that expires in a few minutes. The Node.js Backend Architecture and API Security post covers rate limiting and other protections that belong around upload endpoints, and the Streams and Buffers post explains how files can be moved without loading them fully into memory.

The Complete Upload Route, Tested End to End

Putting it together: disk storage outside the web root, random names, an allow-list filter, a 2 MB limit, and the shared error handler from earlier.

// upload.js
const path = require('node:path');
const { randomUUID } = require('node:crypto');
const express = require('express');
const multer = require('multer');
const AppError = require('./errors/AppError');
const requestId = require('./middleware/requestId');
const { notFound, errorHandler } = require('./middleware/errorHandler');

const UPLOAD_DIR = path.join(__dirname, 'storage', 'product-images'); // not inside public/
const ALLOWED = {
  'image/jpeg': ['.jpg', '.jpeg'],
  'image/png': ['.png'],
  'image/webp': ['.webp'],
};

const storage = multer.diskStorage({
  destination: UPLOAD_DIR,
  filename: (req, file, cb) => {
    const ext = path.extname(file.originalname).toLowerCase();
    cb(null, `${randomUUID()}${ext}`);
  },
});

function fileFilter(req, file, cb) {
  const ext = path.extname(file.originalname).toLowerCase();
  const allowedExts = ALLOWED[file.mimetype];
  if (allowedExts && allowedExts.includes(ext)) return cb(null, true);
  cb(new AppError('Only JPG, PNG or WEBP images are allowed', 400, 'INVALID_FILE_TYPE'));
}

const upload = multer({
  storage,
  fileFilter,
  limits: { fileSize: 2 * 1024 * 1024, files: 5 }, // 2 MB per file, at most 5 files
});

const app = express();
app.use(requestId);

app.post('/products/:id/image', upload.single('image'), (req, res) => {
  if (!req.file) throw new AppError('Please attach an image in the "image" field', 400, 'FILE_REQUIRED');
  const { originalname, mimetype, size, filename } = req.file;
  res.status(201).json({ success: true, data: { originalname, mimetype, size, filename } });
});

app.use(notFound);
app.use(errorHandler);

When destination is a string, multer creates the folder for you (if you pass a function instead, creating it is your job). A test script started the app on port 3145, sent each case with FormData and Blob, and closed the server. Real results with NODE_ENV=production:

valid png:    201 {"success":true,"data":{"originalname":"vase.PNG","mimetype":"image/png","size":70,
                   "filename":"5b8231f8-8410-4171-836d-c70458f71ef3.png"}}
25 MB photo:  413 {"success":false,"error":{"code":"FILE_TOO_LARGE","message":"File is too large. Maximum size is 2 MB","requestId":"31a9afb2-..."}}
exe as image: 400 {"success":false,"error":{"code":"INVALID_FILE_TYPE","message":"Only JPG, PNG or WEBP images are allowed","requestId":"fd8193d9-..."}}
pdf:          400 {"success":false,"error":{"code":"INVALID_FILE_TYPE","message":"Only JPG, PNG or WEBP images are allowed","requestId":"b12ddc57-..."}}
wrong field:  400 {"success":false,"error":{"code":"LIMIT_UNEXPECTED_FILE","message":"Unexpected file field","requestId":"fbe258ab-..."}}
no file:      400 {"success":false,"error":{"code":"FILE_REQUIRED","message":"Please attach an image in the \"image\" field","requestId":"b8fc3512-..."}}
files on disk: [ '5b8231f8-8410-4171-836d-c70458f71ef3.png' ]

The last line matters for Imran's story: after the 25 MB attempt was rejected, only the one valid image was left in the folder, because multer removed the partial file. The disk no longer fills up, the seller gets a clear 413 with a message they can act on, and the error log records the attempt with a request id. Log successful uploads too (user id, product id, size, stored key), and delete files that are no longer referenced, such as images of deleted products, with a periodic clean-up job.

Putting It All Together: One Request's Journey

Here is the order in which the pieces in this post run for a single request, and where each kind of error is raised. Every error, from any step, ends at the same error handler, which logs it and sends the standard JSON shape.

requestId morgan json / multer 400, 413 auth 401, 403 validation 400 route + DB 404, 409, 500 notFound + errorHandler next(err) / throw / rejection winston logs JSON + requestId + stack JSON error response code, message, requestId

Outside this request flow sit the process-level listeners for unhandledRejection and uncaughtException, which log and exit so a process manager can restart a clean copy, and a central log service where all of this can be searched and turned into alerts.

Common Mistakes (and the Fix)

MistakeWhat happensFix
catch (err) { console.log('something went wrong') }The error is swallowed; no stack, no request, no time in the logLog with winston (message, stack, request id) and rethrow, or do not catch at all
Async routes in Express 4 without a wrapper, or a missing awaitThe request hangs, then the process crashes on the unhandled rejectionUpgrade to Express 5 or use asyncHandler; always await promises inside try
Error middleware with three parameters, or registered before the routesExpress skips it and sends its default HTML pageUse (err, req, res, next) and add it last, after notFound
Sending err.message and stack for every 500Database details, file paths and library versions leak to attackersGeneric message plus request id in production; full details only in logs
Logging passwords, tokens, OTPs, card or Aadhaar numbersSecrets copied into files and log services: a data leakRedaction in the logger, log ids instead of values, mask to the last four digits
Uploads with no fileSize limit and trust in file.mimetypeA 25 MB photo fills the disk; a script renamed to .png is storedSet limits, return 413, allow-list type and extension, check magic bytes, random names, store outside the web root

My Opinion

Build the central error handler and AppError on day one. They are about sixty lines together and change how you write every route afterwards: routes throw, one place answers. Adding them later means hunting down dozens of slightly different error responses.

Use Express 5 for new projects and remove asyncHandler from old ones as you upgrade. Automatic forwarding of rejected promises removes a whole class of "the server died on one request" incidents. Keep try/catch only where you actually do something with the error.

Log JSON from the start, with a request id on every line. Pretty text logs feel friendlier for a week; after that, being able to search by requestId, orderId or status is worth far more. Put the redaction step in the logger so nobody has to remember it.

When something unexpected escapes, crash and restart. Handlers for uncaughtException that keep the server running hide bugs and leave it in an unknown state. Log, exit with code 1, and let PM2, systemd or your container platform bring back a clean process.

Validate everything at the edge with a schema library, and send uploads to object storage. Hand-written checks are good for learning, but a schema is easier to review and reuse. For files, set limits, check real content, generate names yourself, and let S3 or a similar service do the storing.

Try It Yourself

Answer these in your own words first, then check the answers. For questions 2 and 6, run the code to confirm.

1. An API has POST /orders. Which status code and error code would you return when:
   (a) the product does not exist (b) the token is invalid (c) quantity is -2
   (d) the database is unavailable (e) the user is logged in but the order belongs to someone else?
2. What does this print, and does the process keep running?
   try { Promise.reject(new Error('late')); } catch (e) { console.log('caught'); }
3. Your error middleware is (err, req, res) => { ... }. Why does Express never call it?
4. Classify each as info, warn or error: seller login, product created,
   payment failed, inventory running low, 5 failed logins for one account in a minute.
5. Name four things you must never write to a log.
6. In a validator, what is the result of  'hello' <= 0  and  undefined <= 0 ?
   Why does that matter for "if (price <= 0) reject"?
7. A file arrives with mimetype 'image/png' and name 'photo.png'. Can you be sure it is a PNG?
   What would you check?
8. For product images, a GST certificate and a shop logo, decide: public or private,
   maximum size, allowed types and where to store each.
Show answers
1. (a) 404 PRODUCT_NOT_FOUND (some APIs use 400/422 since the product id is in the body)
   (b) 401 UNAUTHENTICATED  (c) 400 VALIDATION_ERROR with details for "quantity"
   (d) 503 or 500 with a generic message, full error only in the log  (e) 403 FORBIDDEN
2. Nothing is printed by the catch. try/catch does not see a rejection without await.
   The process crashes with "Error: late" and exit code 1 (default since Node.js 15).
3. Express identifies error middleware by its four parameters. With three, it is treated
   as normal middleware and skipped when an error is passed with next(err).
4. info: seller login, product created. warn: inventory running low.
   error: payment failed. The 5 failed logins: each failure is warn; the pattern is
   something to alert on (possible password guessing).
5. Any four of: passwords, access/refresh tokens or session ids, API keys and secrets,
   OTP codes, full card numbers or CVV, Aadhaar/PAN/bank account numbers.
6. Both are false. So "if (price <= 0)" lets a string or a missing price through.
   Check the type first: typeof price === 'number' && Number.isFinite(price).
7. No. mimetype and the file name are both chosen by the client. Check the first bytes
   (PNG starts with 89 50 4E 47 0D 0A 1A 0A), or re-encode the image with an image library.
8. Product images: public (CDN), about 2-5 MB, JPG/PNG/WEBP, object storage such as S3.
   GST certificate: private bucket, about 5 MB, PDF/JPG/PNG, served only via a short-lived
   pre-signed URL after a permission check. Shop logo: public, about 1 MB, PNG/WEBP/JPG
   (avoid SVG unless sanitised), object storage behind a CDN.

Frequently Asked Questions

Do I still need try/catch in Express 5?

Not just to forward errors: Express 5 passes rejected promises from async routes to your error middleware automatically. You still need try/catch when you want to react to a specific error, such as converting a duplicate-key database error into a 409, retrying a flaky call, cleaning up a half-finished operation, or adding a cause. Code outside the request, such as timers and background jobs, also needs its own handling.

Should I use morgan or winston?

Usually both, for different jobs. Morgan writes one line per HTTP request with method, URL, status and time. Winston logs everything else: business events, warnings and errors with stack traces, in JSON, to files or other destinations. Many apps pipe morgan's output into winston through the stream option so all logs share one format.

What is the difference between 401 and 403?

401 means "I don't know who you are": the token is missing, invalid or expired, so the client should log in again. 403 means "I know who you are, but you are not allowed to do this": logging in again will not help. Returning 403 for a missing token, or 401 for a permission problem, confuses front-end logic that decides whether to show the login screen.

Is frontend validation enough?

No. Frontend validation only improves user experience; anyone can call your API directly and skip it. Backend validation is mandatory for security and data integrity. Do both: the frontend for quick feedback, the backend as the real gatekeeper.

Should uploaded files be stored in the database?

Rarely. Large binary data makes the database bigger, backups slower and queries heavier. Store files in object storage such as S3 (or on disk for small projects) and keep only the key or URL and details like size, type, owner and original name in the database.

Key Takeaways

  • Separate operational errors (expected: bad input, missing data, outages) from programmer errors (bugs). Handle the first gracefully; log and fix the second.
  • try/catch only catches synchronous throws and awaited rejections. Always throw Error objects, and use cause to keep the original reason.
  • An AppError class with statusCode and code, plus one four-argument error middleware after a 404 catch-all, gives every failure the same JSON shape and a request id.
  • Express 5 forwards rejected promises from async routes automatically; on Express 4, wrap async routes with asyncHandler.
  • Never send stack traces or internal messages to clients in production. On unhandledRejection or uncaughtException, log, exit with code 1 and let a process manager restart.
  • Use morgan for request lines and winston for JSON application logs with levels, file transports, request ids and redaction. Never log passwords, tokens, OTPs, card or Aadhaar numbers.
  • Validate every input on the backend, early, with field-level messages; check types before ranges.
  • For uploads: set limits.fileSize and return 413, allow-list type and extension, check magic bytes because mimetype can be spoofed, generate random names, and store outside the web root or in object storage.

Next, read Node.js Backend Architecture: API Security, Rate Limiting, Redis Caching to see how these pieces fit into a larger, secured backend.

References

Related Articles

Post a Comment

0 Comments