The Complete Production SOP: How to Deploy and Run Express Async Errors & Centralized Error Middleware in Autonomous AI Agents

---
name: "express-async-errors-middleware"
description: "Eliminate unhandled promise rejections and try-catch boilerplate in Express applications."
metadata:
  runtime_compatibility: ["codex", "claude-code", "cursor", "windsurf"]
triggers:
  - "handle async errors express"
  - "express centralized error middleware"
  - "express 5 error handling"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

export class AppError extends Error {
  public readonly statusCode: number;
  public readonly isOperational: boolean;
  public readonly code?: string;

  constructor(message: string, statusCode = 500, code?: string) {
    super(message);
    this.statusCode = statusCode;
    this.isOperational = true;
    this.code = code;
    Object.setPrototypeOf(this, new.target.prototype);
    Error.captureStackTrace(this, this.constructor);
  }
}

import 'express-async-errors'; // Must be top import for Express 4
import express, { Request, Response, NextFunction } from 'express';
import { AppError } from './errors/AppError';
import { userRouter } from './routes/userRoutes';

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

app.use('/api/users', userRouter);

// Centralized 4-arity error middleware
app.use((err: Error | AppError, req: Request, res: Response, next: NextFunction) => {
  const statusCode = err instanceof AppError ? err.statusCode : 500;
  const message = err.message || 'Internal Server Error';
  
  res.status(statusCode).json({
    success: false,
    error: {
      message,
      ...(err instanceof AppError && err.code ? { code: err.code } : {}),
      ...(process.env.NODE_ENV !== 'production' ? { stack: err.stack } : {})
    }
  });
});

export default app;

import request from 'supertest';
import app from '../app';

describe('Async Error Boundary', () => {
  it('catches async exceptions and maps to centralized JSON error response', async () => {
    const res = await request(app).get('/api/users/simulate-rejection');
    expect(res.status).toBe(404);
    expect(res.body.success).toBe(false);
    expect(res.body.error.message).toBe('User not found');
  });
});