The Error-Handler plugin provides custom error pages and error logging for HTTP error responses. It replaces generic error messages with user-friendly, branded error pages and logs error occurrences for monitoring.
When web applications encounter errors, they typically return bare-bones error messages that aren't helpful to users. The error-handler plugin intercepts error responses (4xx and 5xx status codes) and replaces them with custom HTML pages. It can load custom error pages from files or generate default styled error pages automatically.
The error-handler plugin is configured as part of the plugin pipeline in your host configuration:
<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
<span itemprop="library">file://./plugins/error-handler.so</span>
<meta itemprop="error_page_404" content="404.html">
<meta itemprop="error_page_500" content="500.html">
<meta itemprop="log_errors" content="true">
</li>| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
error_page_{code} |
String | No | See defaults | Path to custom error page for specific status code (e.g., error_page_404) |
log_errors |
Boolean | No | true | Whether to log error occurrences |
If not configured, the plugin looks for these default error page files:
404.html - Not Found errors500.html - Internal Server errors403.html - Forbidden errorsCreate HTML files in your document root for each error type you want to customize:
<!-- 404.html -->
<!DOCTYPE html>
<html>
<head>
<title>Page Not Found - My Site</title>
<style>
body {
font-family: Arial, sans-serif;
text-align: center;
padding: 50px;
background-color: #f0f0f0;
}
.error-container {
background: white;
padding: 40px;
border-radius: 10px;
box-shadow: 0 2px 10px rgba(0,0,0,0.1);
max-width: 600px;
margin: 0 auto;
}
h1 { color: #ff6b6b; }
.error-code { font-size: 72px; margin: 20px 0; }
a { color: #4CAF50; text-decoration: none; }
</style>
</head>
<body>
<div class="error-container">
<div class="error-code">404</div>
<h1>Oops! Page Not Found</h1>
<p>The page you're looking for doesn't exist.</p>
<p><a href="/">← Go back home</a></p>
</div>
</body>
</html>When custom error pages aren't available, the plugin generates styled error pages automatically:
<!DOCTYPE html>
<html>
<head>
<title>Error 404</title>
<style>
/* Professional styling included */
</style>
</head>
<body>
<div class="error-container">
<div class="error-code">404</div>
<h1>Not Found</h1>
<p>We apologize for the inconvenience. Please try again later or contact support if the problem persists.</p>
<p><small>Error generated by rusty-beam server</small></p>
</div>
</body>
</html>Typical pipeline order:
1. basic-auth.so → May generate 401 errors
2. authorization.so → May generate 403 errors
3. selector-handler.so → Processes requests
4. file-handler.so → May generate 404 errors
5. error-handler.so → Handles all error responses ✓
6. access-log.so → Logs final responsesWhen log_errors is enabled, the plugin logs error details:
[ErrorHandler] 404 error for path: /missing-page.html (host: example.com)
[ErrorHandler] 500 error for path: /api/broken (host: api.example.com)
[ErrorHandler] 403 error for path: /admin/secret (host: example.com)Use error logs to:
<!-- Use default error pages -->
<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
<span itemprop="library">file://./plugins/error-handler.so</span>
</li><!-- Specify custom error page paths -->
<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
<span itemprop="library">file://./plugins/error-handler.so</span>
<meta itemprop="error_page_404" content="errors/not-found.html">
<meta itemprop="error_page_500" content="errors/server-error.html">
<meta itemprop="error_page_403" content="errors/forbidden.html">
<meta itemprop="error_page_401" content="errors/unauthorized.html">
</li><!-- Custom pages without logging -->
<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
<span itemprop="library">file://./plugins/error-handler.so</span>
<meta itemprop="log_errors" content="false">
</li># Test 404 error page
curl http://localhost:3000/this-page-does-not-exist
# Test 403 error (if authorization plugin is configured)
curl http://localhost:3000/forbidden-resource
# Test custom error page
curl -I http://localhost:3000/missing.html
# Check Content-Type: text/html header| Issue | Cause | Solution |
|---|---|---|
| Generic error pages showing | Custom pages not found | Check file paths and document root |
| Errors not being caught | Plugin placement in pipeline | Move error-handler after content plugins |
| No error logs | Logging disabled or wrong placement | Enable log_errors and check pipeline order |
| Wrong content type | Plugin overwriting headers | Plugin sets correct text/html content type |
| Infinite error loops | Error page triggering errors | Ensure error pages are static and error-free |
Run the server with -v flag to see error handling:
./rusty-beam -v config.htmlThe access-log plugin will log the final status code after error page replacement. Original error codes are preserved in the response status.
The security-headers plugin can add security headers to error pages. Place it after error-handler for this to work.
Error pages can be compressed by the compression plugin if placed after error-handler.