Documentation

SafeError & SafeError Pro – Installation, configuration, FAQ and troubleshooting.

Show:

SafeError

Install SafeError

Download the plugin or install it via Plugins → Add New in WordPress. Activate SafeError – Crash Protection & Error Recovery. Go to SafeError in the admin menu to configure the title, message and maintenance image. Optionally install the MU-Plugin from the same page for maximum interception. The free version works fully on its own; no licence required.

Install the MU-plugin

The MU-plugin (must-use) loads SafeError before other plugins so it can intercept errors that occur during plugin loading—errors the standard plugin might miss. Installation is optional and done in one click from SafeError settings. It is recommended for maximum protection. The loader runs early in the WordPress bootstrap.

Dashboard

The SafeError dashboard shows protection status, email notification status, and statistics (errors today, last 7 days, total). You can quickly enable or disable maintenance mode and access the main settings from there. All of this is available in the free version.

Error page (title, message, image)

In SafeError → Error Page you set the title and message shown to visitors when an error occurs (HTML allowed). Choose a maintenance image from the media library. You can also enable "Show maintenance page even when there is no error" to display the page to all visitors; in the free version, logged-in administrators do not see it and can access the site normally.

Notifications (email)

In SafeError → Notifications you can enable email notifications and set the recipient address. You will be alerted when a critical error occurs. The free version includes basic email alerts with anti-spam (throttling). SafeError Pro adds filters by error type and custom sender.

Safe Mode

Safe mode loads WordPress with only SafeError active, so you can isolate problematic plugins. You enter safe mode from the recovery actions on the error page (as an administrator). From the Safe Mode admin page you can exit safe mode or re-enable plugins one by one. This is a free feature; the MU-plugin helps ensure safe mode is available even when plugins fail to load.

Recovery actions (safe mode, disable plugin)

For administrators: when an error is intercepted, the error page shows recovery actions. You can click "Enter safe mode" to load WordPress with only SafeError active, or "Disable [plugin name]" to deactivate the suspected plugin (when component detection identifies it). These actions are only visible to logged-in users with manage_options. In the free version there is no automatic rollback—recovery is manual.

Visitors vs administrators

SafeError: Visitors see only the maintenance page (title, message, image). Logged-in administrators do not see the maintenance page and can access the site normally. Error details are sent by email (if enabled) and are visible in the browser console (F12) for logged-in admins. Recovery options are: Enter safe mode, or Disable the suspected plugin. To stop showing the maintenance page when there is no error, disable the maintenance option in settings or deactivate the plugin. There is no auto-rollback.

SafeError Pro: Same by default, plus you can optionally show the maintenance page to administrators too. Pro adds automatic recovery: auto rollback after a crash, Recovery Engine with backups and one-click restore, error history, webhooks, and scheduled maintenance.

What the free version does not include

The free version does not include: automatic rollback after a crash, error history with search and CSV export, local backups before plugin/theme updates, webhooks (Slack, Discord, Teams), uptime monitoring or scheduled maintenance windows, advanced page customization (layout, branding), or the option to show the maintenance page to administrators. To get these, use SafeError Pro.

SafeError Pro

SafeError Pro: installation and licence

Install and activate SafeError first, then install SafeError Pro. Activate SafeError Pro (a licence may be required). Configure Pro features in SafeError settings. SafeError Pro requires SafeError to be installed and activated. If you deactivate Pro, the free plugin continues to handle errors and maintenance; Pro features are unavailable until you reactivate Pro.

Pro features overview

SafeError Pro adds: Error history with search and CSV export, Recovery Engine and recovery logs, local backups before plugin/theme updates and restore from dashboard, auto rollback after a crash, webhooks (Slack, Discord, Teams, generic), uptime monitoring and "site back online" alerts, scheduled maintenance windows, advanced page customization and branding, multisite support, and safe crash test for debugging.

Recovery Engine

The Recovery Engine automates recovery when a crash occurs: it can disable the faulty plugin, switch to a fallback theme, and run diagnostics. You configure rules and protections from the Recovery Engine admin page. Recovery logs and stats help you see what happened. This is in addition to the free recovery actions (safe mode, disable plugin) which remain available.

Auto rollback

When a crash occurs shortly after a plugin or theme update, SafeError Pro can automatically restore the previous version. It uses local backups first (for any plugin or theme), then falls back to WordPress.org for plugins from the repository. After a successful rollback, visitors see a brief "Restored, reloading..." message. Rollback depends on recent update detection and available backups or previous versions.

Backups before updates

SafeError Pro creates local backups automatically before each plugin or theme update. If an update causes a crash, you can restore the previous version in one click—including premium and custom plugins that are not on WordPress.org. Backups are stored in wp-content/uploads/saferror-backups/ and can be managed from the Recovery Engine page. Retention and purge are configurable.

Error history and CSV export

Pro stores each error (fatal, wp_die) in an error log with type, message, file, line, first/last seen, and status. You can search, filter, and exclude entries. Export to CSV for analysis. Dashboard analytics show error trends. This complements the free behaviour where details are only in email and browser console.

Webhooks (Slack, Discord, Teams)

SafeError Pro can send webhook notifications to Slack, Discord, Microsoft Teams, or a generic URL. You can trigger alerts on critical errors, recovery actions (e.g. plugin disabled, rollback), uptime down/up, and maintenance on/off. Configure webhook URLs in SafeError Pro → Notifications. Throttling helps avoid spam.

Uptime monitoring

Pro checks site availability periodically (via WP-Cron) and can alert you when the site goes down or comes back online. Alerts can be sent by email, webhook, or browser notification. This is internal monitoring (your server runs the checks), not an external 24/7 monitoring service.

Scheduled maintenance

Pro lets you schedule maintenance windows: set a date/time or a duration. Maintenance mode is then enabled and disabled automatically. In addition, Pro can optionally show the maintenance page to administrators (in the free version only visitors see it; admins always have normal access).

Advanced customization and branding

Pro adds layout options (fullscreen/boxed), opacity, colors, typography, and fullscreen background for the error/maintenance page. You can customize branding and footer (e.g. credit, custom footer text). These options are in addition to the free title, message and image.

Licence and updates

SafeError Pro licence and updates are managed by the licence provider (e.g. Freemius). If you deactivate SafeError Pro, your error logs and monitoring data remain stored. The free plugin continues to handle errors and maintenance. Pro features are unavailable until you reactivate Pro.

Free vs Pro comparison

When to use SafeError

Use the free version when you want to hide errors from visitors, show a clean maintenance page, get email alerts and console debug for admins, and recover manually via safe mode or disabling the suspected plugin. The free version is sufficient for many small sites and developers who can intervene quickly. No auto-rollback or error history; recovery is manual.

When to use SafeError Pro

Use Pro when you need automatic recovery (auto rollback, Recovery Engine), error history and CSV export, backups before updates, webhooks (Slack, Discord, Teams), uptime monitoring, scheduled maintenance, or advanced page customization. Pro is suited to agencies, e-commerce, and any site where downtime must be minimized and recovery automated.

Use cases: Free vs Pro

Free: personal or small business site, developer who can fix issues quickly, need only maintenance page + email + manual recovery. Pro: agency managing client sites, e-commerce or high-availability site, need error logs and audits, want automatic rollback and backups, need alerts in Slack/Teams/Discord or scheduled maintenance windows.

Technical

How it works (buffering, handlers)

SafeError uses output buffering to intercept WordPress error messages before they are sent to the browser. It registers a custom handler for wp_die() and PHP fatal errors, and uses template_redirect for manual maintenance mode. The optional MU-plugin loader starts interception earlier in the bootstrap process.

Component detection (plugin/theme)

From the error file path, SafeError identifies the plugin or theme responsible. This "component detection" lets you know exactly what to fix without digging through stack traces. The suspected component is shown on the error page (for admins) and in crash reports. Available in both free and Pro.

FAQ

What is SafeError?

SafeError is a WordPress plugin that intercepts PHP errors and WordPress critical screens, hides them from visitors, and replaces them with a clean maintenance-style page while safely logging the technical details for administrators. The free version is fully functional; Pro adds automatic recovery, error history, backups, webhooks, and more.

What does SafeError do?

SafeError hides PHP errors and critical output from the frontend, identifies the plugin or theme responsible (component detection), shows a customizable maintenance page, offers recovery actions (safe mode, disable plugin), sends basic email notifications, and exposes debug details in the browser console (F12) for logged-in admins. It optionally uses a MU-plugin for earlier interception. Pro adds Recovery Engine, auto rollback, backups, error history, webhooks, monitoring, and scheduled maintenance.

What extra features does SafeError Pro add?

On top of SafeError, SafeError Pro adds: Recovery Engine, error history with search and CSV export, local backups before plugin/theme updates, auto rollback after a crash, webhooks (Slack, Discord, Teams), uptime monitoring, scheduled maintenance, advanced page customization and branding, multisite support, and safe crash test for debugging. You can also show the maintenance page to administrators.

Who is SafeError for?

SafeError is ideal for businesses and professional websites where brand image matters, agencies managing multiple client sites, developers and technical teams who want an extra safety layer in production, and any WordPress site in production where visitors should never see raw PHP or WordPress error messages.

How does SafeError work technically?

SafeError uses output buffering and custom handlers for wp_die() and PHP fatal errors. It replaces technical output with a controlled HTML page, detects the plugin or theme from the error file path, and logs details for admins (console, email; Pro: error log). Recovery actions and safe mode are available for admins. The optional MU-plugin loader starts interception earlier in the bootstrap.

Does SafeError work without the Pro add-on?

Yes. The free version is fully functional on its own: component detection, recovery actions, safe mode, dashboard analytics, customizable maintenance page, and email notifications. SafeError Pro is an optional add-on for error history, auto rollback, backups, monitoring, and advanced customization.

What PHP versions does SafeError support?

SafeError is compatible with PHP 7.4 through PHP 8.x. The plugin is tested on current PHP versions to ensure reliable error interception and recovery.

How do I install SafeError?

Install via Plugins → Add New in WordPress (search for "SafeError") or download from WordPress.org. Activate the plugin, then go to SafeError in the admin menu to configure the title, message and maintenance image. Optionally install the MU-plugin from the same page for earlier interception.

What is the MU-plugin and should I install it?

The MU-plugin (must-use plugin) loads SafeError before other plugins. That lets it intercept errors that occur during plugin loading, which the standard plugin might miss. Installation is optional and done in one click from SafeError settings. It is recommended for maximum protection.

Where can I see full error details (file, line, message)?

When logged in as an administrator, open Developer Tools (F12) and go to the Console tab. SafeError outputs technical details there (type, message, file, line). You can enable or disable this in SafeError → Error Page → "Debug console output". SafeError Pro also stores errors in the Error History with search and CSV export.

Does SafeError Pro create backups before updates?

Yes. SafeError Pro creates local backups automatically before each plugin or theme update. If an update causes a crash, you can restore the previous version in one click—including premium and custom plugins that are not on WordPress.org. Backups are stored in wp-content/uploads/saferror-backups/ and can be managed from the Recovery Engine page.

How does auto rollback work?

When a crash occurs shortly after a plugin or theme update, SafeError Pro can automatically restore the previous version. It uses local backups first (for any plugin or theme), then falls back to WordPress.org for plugins from the repository. After a successful rollback, visitors see a brief "Restored, reloading..." message instead of an error page.

Can I get notified on Slack, Discord or Teams when an error occurs?

Yes. SafeError Pro includes webhooks for Slack, Discord and Microsoft Teams. You can send alerts when a critical error is detected or when a recovery action (e.g. plugin disabled, rollback) is performed. Configure your webhook URLs in SafeError Pro → Notifications.

Can I enable maintenance mode without an error?

Yes. In SafeError settings, check "Show maintenance page even when there is no error". In the free version, visitors see the maintenance page while logged-in administrators can access the site normally. In SafeError Pro you can optionally show the maintenance page to administrators too. Pro also adds scheduled maintenance windows (date/time or duration).

Does SafeError affect performance?

SafeError is lightweight. It uses output buffering and error handlers that run only when needed. The MU-plugin adds minimal overhead. No server configuration (e.g. php.ini) is required—everything works from within WordPress.

Troubleshooting

The error message still shows to visitors

Ensure SafeError is active and that error output replacement is enabled in SafeError settings. Some errors occur before plugins load: install the MU-plugin from SafeError settings for earlier interception. Clear any full-page or object caches.

Email notifications are not sent

Check that email notifications are enabled in SafeError → Notifications and that the recipient address is valid. Some hosts block or delay PHP mail(). Try an SMTP plugin if needed. Check the spam folder.

The MU-plugin does not load

Ensure the mu-plugins directory exists (wp-content/mu-plugins) and is writable. Reinstall the MU-plugin from SafeError settings. On some hosts the directory may be named "must-use plugins". Check that the file was created and has no PHP errors.

Developers

Hooks and filters

SafeError and SafeError Pro expose filters and actions for customizing behavior (e.g. error template, notification content). Check the plugin code or developer documentation for the full list. Common hooks include filters for the maintenance page content and actions after recovery.