Overview

Arkos ships a global error handler that sits at the end of the Express middleware chain and processes every error thrown or passed via next(err) across your application. It normalizes errors into a consistent response shape, maps known error types (Prisma, JWT, validation) to human-readable messages, and adjusts the level of detail it exposes based on the current environment.

You never register this handler yourself — Arkos wires it in automatically.

How It Works

When any middleware, interceptor, service hook, or controller throws an error or calls next(err), Express forwards it to the global error handler. From there:

1. The error is matched against known types — Prisma errors, JWT errors, validation errors — and mapped to a friendly message and status code.
2. The response is shaped based on the environment.
3. The response is sent to the client.

Because ArkosRouter wraps all handlers with catchAsync automatically, you never need to wrap your own handlers — thrown errors are always caught and forwarded correctly.

Environments

Arkos determines the environment through its own CLI commands, not through NODE_ENV:

• Development — run with npx arkos dev. Full error details are exposed including stack traces, useful for debugging.
• Production — run with npx arkos start. Responses are sanitized. Stack traces are hidden. Non-operational errors return a generic message.

Development Response

{
  "message": "User not found with id: 123",
  "code": "NotFound",
  "statusCode": 404,
  "status": "fail",
  "isOperational": true,
  "meta": {},
  "stack": [
    "AppError: User not found with id: 123",
    "    at findOne (/src/modules/base/base.controller.ts:25:11)"
  ]
}

Production Response

Operational errors (expected failures like 404, 403, 400) include the message:

{
  "status": "fail",
  "message": "User not found with id: 123",
  "code": "NotFound",
  "meta": {}
}

Non-operational errors (programming errors, unexpected failures) return a generic message to avoid leaking internals:

{
  "status": "error",
  "message": "Internal server error, please try again later.",
  "code": "Unknown",
  "meta": {}
}

What's Next

• Usage — throwing errors correctly with AppError
• Error Messages — how Arkos formats validation, authentication, and Prisma errors
• Custom Handler — adding your own error handler after Arkos's