Error custom pages
Shows a user-friendly page when a fatal error or exception occurs, with UUID tracking for support reference.
error_page
Install
composer require 'drupal/error_page:^2.0'
Overview
The Error custom pages module replaces Drupal core's plain error pages with customizable, user-friendly pages when exceptions or fatal errors occur. Each error is tagged with a Universally Unique Identifier (UUID), enabling users to reference specific errors when contacting support. The UUID is also logged to Drupal's watchdog and PHP error log for easy debugging.
Unlike typical Drupal modules, this module uses settings.php for configuration instead of Drupal's configuration management system. This design choice is intentional: when an uncaught exception occurs, Drupal services (including the configuration factory) may not be available. By relying on settings.php, the module can still function even when the Drupal container is broken or unavailable.
The module provides customizable HTML templates for error pages and messages. Since the Twig rendering engine requires Drupal services, the module uses simple static HTML files with variable token replacement. These templates can be copied and customized while keeping them protected from public web access.
Features
- Displays user-friendly error pages instead of Drupal core's plain error output when exceptions or fatal errors occur
- Generates a unique UUID for each error/exception, displayed to users and logged for support reference
- Provides customizable HTML templates for error pages (error_page.html) and error messages (error_message.html)
- Logs errors to both Drupal's database log (watchdog) and PHP error log with UUID reference
- Uses settings.php configuration instead of Drupal config system to ensure functionality even when Drupal services are unavailable
- Supports custom error log destinations via PHP's error_log() function configuration
- Protects markup templates from public access with .htaccess security rules
- Compatible with Drupal 10 and Drupal 11
Use Cases
Production site error handling
Replace Drupal's technical error messages with user-friendly pages on production sites. Users see a polite message with a UUID they can reference when contacting support, while developers can look up the UUID in logs to find the exact error details.
Support ticket correlation
When users report errors to your help desk, they can provide the UUID shown on the error page. Support staff can then search Drupal's database log (dblog) or PHP error logs for that UUID to quickly identify the exact error, stack trace, and context.
Branded error pages
Customize the error page templates to match your site's branding. Copy error_page.html and error_message.html to a secure directory, add your site's logo, CSS, and messaging, then configure the template_dir setting to use your custom templates.
Custom error logging destinations
Route error logs to a specific file for monitoring or integration with external logging systems. Configure log method 3 with a destination path to collect all errors in a dedicated log file.
Tips
- Place custom templates outside the web root or protect them with .htaccess to prevent direct public access
- Use verbose error logging during development ($config['system.logging']['error_level'] = 'verbose') to see full backtraces on error pages
- The {{ error_report }} variable in templates is empty when error display is disabled in Drupal's logging settings
- Enable the error_page_test submodule (requires $settings['extension_discovery_scan_tests'] = TRUE) to test different error types at /error_page_test/exception, /error_page_test/fatal_error, /error_page_test/user_error, and /error_page_test/php_notice
- The module logs critical errors to both Drupal's database log and PHP's error log for redundancy
Technical Details
Troubleshooting 4
Ensure you have added both set_error_handler() and set_exception_handler() calls to your settings.php file. The module requires explicit registration of its error handlers in settings.php.
If not using Composer for autoloading, add this line before the set_error_handler calls in settings.php: require_once 'modules/contrib/error_page/src/ErrorPageErrorHandler.php'; Composer users get this automatically via the classmap autoload entry.
Check that $settings['error_page']['uuid'] is not explicitly set to FALSE in your settings.php. The default is TRUE, but it may have been disabled.
Verify that $settings['error_page']['template_dir'] points to the correct directory and that the template files are named exactly error_page.html and error_message.html. The directory path should be absolute or relative to DRUPAL_ROOT.
Security Notes 4
- Never enable $settings['extension_discovery_scan_tests'] on production sites, as it allows discovery of test modules
- Custom template directories should be protected from public web access using .htaccess or by placing them outside the web root
- The module automatically strips DRUPAL_ROOT from file paths in error messages to prevent full path disclosure (OWASP security best practice)
- The default markup/ directory includes an .htaccess file that denies all public access to template files