/ 
PAGI-0.001006
/ PAGI::Middleware::ErrorHandler

NAME

PAGI::Middleware::ErrorHandler - Exception handling middleware

SYNOPSIS

use PAGI::Middleware::Builder;

my $app = builder {
    enable 'ErrorHandler',
        development => 1,
        on_error    => sub  {
    my ($error) = @_; warn "App error: $error" };
    $my_app;
};

DESCRIPTION

PAGI::Middleware::ErrorHandler catches exceptions thrown by the inner application and converts them to appropriate HTTP error responses.

CONFIGURATION

  • development (default: 0)

    If true, include stack trace in error responses. Should be false in production.

  • on_error (default: undef)

    Callback invoked with the error when an exception is caught. Useful for logging.

    on_error => sub  {
    my ($error) = @_; $logger->error($error) }

  • content_type (default: 'text/html')

    Content type for error responses. Supported: 'text/html', 'application/json', 'text/plain'

  • status (default: 500)

    HTTP status code for general exceptions.

EXCEPTION HANDLING

The middleware supports exception objects with a status_code method to set custom HTTP status codes:

package My::Exception;
sub new { bless { status => $_[1], message => $_[2] }, $_[0] }
sub status_code { $_[0]->{status} }

# In app:
die My::Exception->new(404, 'Resource not found');

NOTES

  • If the response has already started when an error occurs, the middleware cannot send an error page. It will log the error and return.

  • In development mode, the full error message and stack trace are included in the response. In production, only a generic message is shown.

  • For non-HTTP requests (WebSocket, SSE), errors are propagated without transformation.

SEE ALSO

PAGI::Middleware - Base class for middleware