What error handling is built into the app?

Koa has built-in error handling through the onerror method in the context object. Here's what's built into the app:

Error Handling Mechanism

Context-level error handling is implemented in [lib/context.js:L106-L163]. When an error occurs, the onerror method:

1. Validates the error: Converts non-Error objects to Error instances. If a non-error value is thrown, it's stringified using util.format('non-error thrown: %j', err) [lib/context.js:L118-L119]

2. Delegates to app-level handler: Emits the error to the app via this.app.emit('error', err, this) [lib/context.js:L125], allowing you to register error listeners at the application level.

3. Clears headers: If headers haven't been sent yet, it removes all previously set headers and allows the error response to set new ones [lib/context.js:L140-L146]

4. Sets default status code: Uses err.status or err.statusCode if valid (must be a number with a valid HTTP status message). Defaults to 500 if missing or invalid [lib/context.js:L152-L153]

5. Responds with error message: Responds with either the error message (if err.expose is true) or a generic HTTP status message (e.g., "Internal Server Error") [lib/context.js:L156-L161]

App-level Error Events

The app emits 'error' events that you can listen to. Tests show this in action—for example, [tests/application/currentContext.test.js:L59-L71] shows an error handler receiving both the error and context.

Async LocalStorage Support

Koa can optionally track context during error handling via asyncLocalStorage. When enabled with new Koa({ asyncLocalStorage: true }), app.currentContext returns the context even in error handlers [tests/application/currentContext.test.js:L54-L71].

FOLLOW_UPS:

• How does middleware handle errors with the next() function?
• Can you customize error responses beyond status and message?
• What happens if headers are already sent when an error occurs?