Error Handling

// Operational error: expected, handle gracefully
try {
  const user = await db.users.findById(id);
} catch (err) {
  if (err.code === 'CONNECTION_TIMEOUT') return res.status(503).json({ error: 'Service temporarily unavailable' });
}

// Programmer error: a bug, shouldn't be silently swallowed
// TypeError: Cannot read properties of undefined -- indicates broken code, not a recoverable condition

Common follow-ups: Why is it dangerous to catch and ignore a programmer error like a TypeError rather than letting the process crash?;How do custom error classes help distinguish operational from programmer errors at the point they're caught?

class ValidationError extends Error {
  constructor(message, field) {
    super(message);
    this.name = 'ValidationError';
    this.field = field;
    this.statusCode = 400;
    this.isOperational = true;
  }
}

if (!email.includes('@')) throw new ValidationError('Invalid email format', 'email');

Common follow-ups: How do you ensure a custom Error subclass's stack trace still correctly points to where the error was thrown, not where it was constructed?;What's the risk of creating too many overly specific custom error classes versus a more generalized approach with an error 'code' property?

app.get('/users/:id', async (req, res, next) => {
  try {
    const user = await getUserOrThrow(req.params.id);
    res.json(user);
  } catch (err) {
    next(err); // delegate to centralized handler
  }
});

app.use((err, req, res, next) => { // must have exactly 4 params
  logger.error(err);
  const statusCode = err.statusCode || 500;
  res.status(statusCode).json({ error: err.isOperational ? err.message : 'Internal server error' });
});

Common follow-ups: Why does Express require an error-handling middleware to have exactly four parameters to recognize it as such?;How do you ensure an unhandled error inside an async route handler actually reaches this middleware, given Express doesn't automatically catch async errors by default in older versions?

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

app.get('/users/:id', asyncHandler(async (req, res) => {
  const user = await getUserOrThrow(req.params.id); // if this throws, asyncHandler catches and forwards it
  res.json(user);
}));

Common follow-ups: How does Express 5 change this default behavior regarding async route handlers?;What's the risk of forgetting to wrap even a single async route handler in a codebase relying on this manual pattern?

app.use((err, req, res, next) => {
  if (err.isOperational) {
    return res.status(err.statusCode || 400).json({ error: err.message }); // safe to show details
  }
  logger.error('Unexpected error:', err); // log full details internally
  res.status(500).json({ error: 'Internal server error' }); // generic message to the client
});

Common follow-ups: What specific security risk does leaking a stack trace or internal error message to an API client actually pose?;How would you handle an error that's genuinely ambiguous between being the client's fault and the server's fault?

// try/catch does NOT catch this -- it's an async event, not a synchronous throw
try {
  fs.createReadStream('missing-file.txt').pipe(res);
} catch (err) { /* never reached */ }

// Correct: explicit error listener, or use pipeline()
const { pipeline } = require('node:stream/promises');
try {
  await pipeline(fs.createReadStream('missing-file.txt'), res);
} catch (err) {
  console.error('Stream failed:', err.message); // correctly caught
}

Common follow-ups: Why specifically does a try/catch fail to catch an error emitted asynchronously by an EventEmitter-based API like streams?;What happens to a stream pipeline if one stream in the middle errors but the others don't have error listeners attached?

async function getUserProfile(id) {
  try {
    return await db.users.findById(id);
  } catch (err) {
    throw new Error('Failed to load user profile', { cause: err }); // preserves the original error
  }
}

// Later, when logging or debugging:
console.error(err.message, 'caused by:', err.cause?.message);

Common follow-ups: How did teams handle this same error-wrapping need before the standardized 'cause' property was introduced?;How do logging libraries and error-tracking tools (like Sentry) typically surface and display a full error cause chain?

async function processWithConnection(id) {
  const connection = await pool.connect();
  try {
    return await connection.query('SELECT ...', [id]);
  } catch (err) {
    logger.error(err);
    throw err;
  } finally {
    connection.release(); // always runs, whether the query succeeded or failed
  }
}

Common follow-ups: What happens if the finally block itself throws an error -- does it override an error from the try or catch block?;Why is placing cleanup logic in finally more reliable than duplicating it at the end of both the try and catch blocks?

app.use((err, req, res, next) => { logger.error(err); res.status(500).json({ error: 'Internal server error' }); });

process.on('unhandledRejection', (reason) => { logger.error('Unhandled rejection:', reason); process.exit(1); });
process.on('uncaughtException', (err) => { logger.error('Uncaught exception:', err); process.exit(1); });

Common follow-ups: Why is it important that both unhandledRejection and uncaughtException handlers still call process.exit() rather than just logging and continuing?;How does a process manager like PM2 or Kubernetes ensure the application actually restarts quickly after one of these handlers exits the process?

app.use((err, req, res, next) => {
  logger.error(err.stack); // full details, server-side only

  const isDev = process.env.NODE_ENV !== 'production';
  res.status(500).json({
    error: 'Internal server error',
    ...(isDev && { stack: err.stack }), // only include stack trace outside production
  });
});

Common follow-ups: What other information beyond a raw stack trace should be scrubbed from error responses before they reach a client?;How would you configure a logging tool to still capture this same detailed information without it ever reaching the actual HTTP response?