Replace WordPress's ugly error screens with branded, professional pages -- in one click.
Works immediately on activation. Auto-detects your site name, logo, and brand color. No configuration required.
Current version: 1.0.6 · 5 templates · 149 tests · Zero-config activation
| Purpose | Replace wp_die() and PHP fatal error screens with branded pages |
| Best for | Any WordPress site that cares about user experience during errors |
| Setup | Zero-config -- activate and it works |
| Performance | Zero overhead on normal page loads; only runs when an error occurs |
| API safe | REST API, AJAX, JSON, and JSONP responses are never touched |
| Requires | WordPress 6.4+ · PHP 8.0+ |
- The
wp_die()error screen -- permission errors, expired nonces, security blocks, "Are you sure?" prompts, and any call towp_die()with HTML output. - The PHP fatal error screen -- the white screen of death from uncaught exceptions, parse errors, and out-of-memory errors.
The default WordPress error screen is a plain white page with black text. It looks broken. Visitors don't know if the site is down, hacked, or just having a bad day. Graceful Error Pages replaces it with a page that matches your brand -- instantly.
- Activate the plugin.
- Error pages are branded immediately using auto-detected settings (site name, logo, colors).
- Optionally customize via Settings > Error Pages -- pick a template, adjust colors, edit messaging, add merge tags.
On activation, the plugin reads your site name from bloginfo, your logo from the Customizer, and your brand color from the theme's primary color setting. Everything is auto-configured. You can override any of these in the settings.
Each template is fully self-contained with inline CSS -- no theme dependencies, no external CDN, no build step. They work even when your theme is completely broken.
| Template | Style | Best for |
|---|---|---|
| Minimal (default) | Clean, light, centered | Most sites |
| Corporate | Logo-forward, structured | Business / enterprise |
| Friendly | Warm, encouraging, illustrated | Community / SaaS |
| Dark | Dark background, modern | Developer / tech |
| Starter | Bare minimum styled text | Maximum customization |
Dynamic content in any text field. Type { to get an autocomplete dropdown with available tags:
{site_name}-- your site name{year}-- current year{home_url}-- your site homepage URL{back_url}-- the URL to go back to
Merge tags work in error title, error message, button text, and copyright fields.
Click "Preview Error Page" in the settings to see your changes in a modal iframe -- before saving. The preview reflects unsaved form state so you can iterate quickly.
- Logo and site icon upload
- Brand color, background color, text color
- Error title and message (with merge tags and basic HTML)
- Primary and secondary button text and URL
- Copyright text
- Support link
Error page CSS is fully bundled with the plugin. No theme stylesheet, no CDN, no wp_head() / wp_footer(). This is critical because when wp_die() fires, the theme may not be loaded. During fatals, WordPress's hook system isn't available at all.
The plugin only overrides the HTML die handler. The AJAX, JSON, and JSONP die handlers are left untouched. WP-CLI is detected and skipped automatically. Your REST API, admin-ajax, and CLI workflows are never affected.
By default, error pages only fire on the frontend. In settings, you can extend to admin-only or everywhere. Certain wp-admin contexts (Gutenberg saves, Customizer preview, Site Health) are always excluded to avoid interfering with WordPress internals.
Templates support auto, on, or off dark mode. In auto mode, the error page respects the visitor's prefers-color-scheme preference.
Settings UI follows WCAG 2.1: proper ARIA attributes on the merge tag autocomplete (combobox pattern with listbox, aria-activedescendant, aria-selected), focus trap on the preview modal, keyboard navigation, and focus restoration.
Minimal Template -- the default, replacing the WordPress error screen with a clean, centered layout
Settings -- Design Tab -- template picker, logo, colors, and dark mode
Settings -- Content Tab -- error title, message, buttons, and merge tags
Corporate Template -- logo-forward, structured layout with clear hierarchy
Dark Template -- dark background with modern aesthetic
From WordPress.org: Search for "Graceful Error Pages" in Plugins > Add New, install, and activate.
From source:
git clone https://github.com/codeverbojan/graceful-error-pages.git
cd graceful-error-pages
composer install
npm installThen place the plugin folder in wp-content/plugins/ and activate "Graceful Error Pages" from the WordPress admin.
- WordPress 6.4+
- PHP 8.0+
Does this work out of the box? Yes. Activate it and error pages are branded immediately. No settings required.
Will this break my REST API or AJAX? No. Only the HTML die handler is overridden. REST API, AJAX, JSON, and JSONP handlers are untouched.
Does this affect wp-admin? Not by default. The handler only fires on the frontend unless you enable admin override in settings.
Does this work with WP-CLI? Yes. CLI contexts are detected and skipped automatically.
Does the plugin load anything on every page?
No. The handler is registered on init but only renders when wp_die() is called or a fatal error occurs. Zero performance impact on normal page loads.
Does this work with WooCommerce / page builders / caching plugins? Yes. Error pages are styled independently of your theme or any other plugin. No conflicts.
- PHP 8.0+, Composer 2.x, Node.js 18+, Docker
git clone https://github.com/codeverbojan/graceful-error-pages.git
cd graceful-error-pages
composer install
npm installnpm run env:start # WordPress at http://localhost:8888 (admin / password)
npm run env:stop # Stop
npm run env:clean # Reset databaseThe plugin has 149 unit tests with 409 assertions.
# Unit tests (no WordPress needed, fast)
composer test
# Single test
vendor/bin/phpunit --filter TestClassName::testMethodName
# Linting and static analysis
composer lint # PHPCS (WordPress Coding Standards)
composer lint:fix # PHPCBF auto-fix
composer analyze # PHPStan level 6
# Run everything
composer check # PHP lint + PHPStan + unit tests
# WordPress Plugin Check (needs wp-env running)
npm run plugin-check- PHPCS (WordPress Coding Standards 3.x) + PHPStan level 6
declare(strict_types=1)in every PHP file- PSR-4 autoloading:
GracefulErrorPages\->src/ - Pre-commit: PHPCS on staged files (Husky + lint-staged)
- Pre-push: Full PHPCS + PHPStan + unit tests
See CONTRIBUTING.md for the pull request process.
graceful-error-pages/
├── graceful-error-pages.php # Plugin bootstrap: headers, autoloader, boot
├── uninstall.php # Clean removal of plugin options
│
├── src/ # 8 PHP classes (PSR-4: GracefulErrorPages\)
│ ├── Plugin.php # Bootstrap: boot(), hooks, activate, deactivate
│ ├── Handler.php # wp_die handler + fatal error shutdown handler
│ ├── Settings.php # Admin settings page (WordPress Settings API)
│ ├── TemplateEngine.php # Template loading + merge tag rendering
│ ├── AutoDetect.php # Logo/color/name detection from Customizer
│ ├── Preview.php # AJAX preview endpoint for live preview modal
│ ├── Sanitizer.php # Input sanitization helpers
│ └── Helpers/
│ └── Assets.php # Script/style registration and enqueuing
│
├── templates/ # 5 self-contained error page templates
│ ├── minimal.php # Clean, light, centered (default)
│ ├── corporate.php # Logo-forward, structured
│ ├── friendly.php # Warm, encouraging
│ ├── dark.php # Dark background, modern
│ └── starter.php # Bare minimum styled text
│
├── assets/
│ ├── src/ # Source (git-tracked)
│ │ ├── js/admin.js # Preview modal, color picker, media uploader
│ │ ├── js/merge-tags.js # Merge tag input with pills + autocomplete
│ │ ├── css/admin.css # Settings page styles
│ │ └── css/error-page.css # Error page styles (self-contained)
│ ├── build/ # Webpack output (git-ignored)
│ └── images/ # Template thumbnails + default SVG icon
│
├── tests/
│ ├── Unit/ # 149 PHPUnit tests (Brain\Monkey, no WP needed)
│ └── bootstrap.php # Test bootstrap with WP function stubs
│
├── languages/ # i18n (.pot file)
├── .github/workflows/ # CI + Release pipelines
└── bin/ # Build and release scripts
ci.yml -- runs on every push and PR:
- Lint: PHP syntax check, PHPCS, PHPStan
- Unit tests: PHP 8.1, 8.2, 8.3, 8.4 matrix
- Build: verify distribution zip
release.yml -- triggered by v* tags:
- Full CI including WordPress Plugin Check
- Validates changelog in
readme.txt - Generates
.pottranslation file - Builds distribution zip
- Creates GitHub Release with zip artifact
- Deploys to wordpress.org SVN
bash bin/release.sh 1.0.0 # Bump version, changelog, commit, tag, pushThe release script validates the working tree, bumps version across all sync points (plugin header, constant, readme.txt, composer.json, phpstan-constants.php, bootstrap.php), generates the changelog from conventional commits, and pushes the tag. CI handles the rest.
Custom wp_die() handler, PHP fatal error handler, five templates, admin settings with live preview, merge tag system with autocomplete, auto-detection of site branding, dark mode support, scope control, full i18n, 149-test suite.
Redirect rules, error analytics, custom template editor, multisite network settings, WooCommerce-specific templates, white-label, import/export, error classification.
Contributions are welcome. See CONTRIBUTING.md for guidelines on the development workflow, coding standards, and pull request process.
GPL-2.0-or-later. See LICENSE.
Made by Codever