ErrorHandlerPlugin Schema

Schema definition for the Error Handler Plugin, which provides custom error pages and error logging capabilities.

Schema Information

Property Value
Schema URL https://rustybeam.net/schema/ErrorHandlerPlugin
Parent Schema https://rustybeam.net/schema/HandlerPlugin
Description Custom error pages and error logging for HTTP status codes

Properties

Property Type Cardinality Description
name https://rustybeam.net/schema/Text 0..1 Plugin instance name for logging and identification. Defaults to "error-handler" if not specified.
log_errors https://rustybeam.net/schema/Boolean 0..1 Whether to log error details to the server log. Defaults to true. Set to false to disable error logging.
error_page_404 https://rustybeam.net/schema/Text 0..1 Custom error page file for 404 Not Found errors. Path relative to document root. Defaults to "404.html".
error_page_403 https://rustybeam.net/schema/Text 0..1 Custom error page file for 403 Forbidden errors. Path relative to document root. Defaults to "403.html".
error_page_500 https://rustybeam.net/schema/Text 0..1 Custom error page file for 500 Internal Server Error. Path relative to document root. Defaults to "500.html".
error_page_* https://rustybeam.net/schema/Text 0..n Custom error page for any HTTP status code. Use pattern error_page_XXX where XXX is the status code (e.g., error_page_401, error_page_502).

Usage Examples

Basic Error Handler with Default Pages

<tr itemscope itemtype="https://rustybeam.net/schema/ErrorHandlerPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_error_handler.so</span>
    <span itemprop="log_errors">true</span>
</tr>

Custom Error Pages Configuration

<tr itemscope itemtype="https://rustybeam.net/schema/ErrorHandlerPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_error_handler.so</span>
    <span itemprop="name">custom_errors</span>
    <span itemprop="log_errors">true</span>
    <span itemprop="error_page_404">errors/not-found.html</span>
    <span itemprop="error_page_403">errors/forbidden.html</span>
    <span itemprop="error_page_500">errors/server-error.html</span>
    <span itemprop="error_page_401">errors/unauthorized.html</span>
</tr>

Minimal Configuration (No Logging)

<tr itemscope itemtype="https://rustybeam.net/schema/ErrorHandlerPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_error_handler.so</span>
    <span itemprop="log_errors">false</span>
</tr>
Error Page Resolution
Error page files are resolved relative to the document root. If a custom error page file doesn't exist, the plugin generates a default HTML error page with the appropriate status code and message.

Schema Inheritance

This schema inherits from the HandlerPlugin schema, which provides:

And ultimately from the base Plugin schema, which provides:

Supported Status Codes

The Error Handler Plugin can handle any HTTP status code. Common error codes include:

Status Code Description Default Page
400 Bad Request Generated HTML
401 Unauthorized Generated HTML
403 Forbidden 403.html
404 Not Found 404.html
500 Internal Server Error 500.html
502 Bad Gateway Generated HTML
503 Service Unavailable Generated HTML

Validation Rules

Plugin Pipeline Placement
The Error Handler Plugin should typically be placed near the end of the plugin pipeline, after authentication and authorization plugins but before the file handler. This ensures that errors from other plugins are properly handled.

Error Page Templates

Custom error pages should be HTML files that provide user-friendly error messages. Example 404.html:

<!DOCTYPE html>
<html>
<head>
    <title>Page Not Found</title>
    <style>
        body { font-family: sans-serif; text-align: center; padding: 50px; }
        h1 { color: #e74c3c; }
    </style>
</head>
<body>
    <h1>404 - Page Not Found</h1>
    <p>The page you're looking for doesn't exist.</p>
    <a href="/">Return to Home</a>
</body>
</html>

Integration with Other Plugins

See Also