Fatal Error Recovery Mode in 5.2

WordPress 5.2 will allow administrators to fix or mitigate fatal errors on their site that would previously have been impossible to address without developer interference and modifying the codebase. Even in the case where a fatal error would commonly have made the backend completely inaccessible (for example through a so-called “white screen of death”), administrators will now still have the chance to log in and do something about the issue.

When a fatal error occurs, a user-facing error screen will display that informs the user/visitor that the site is experiencing technical difficulties. More importantly though, when such an error occurs, an email will be sent to the admin email address, informing about the issue and including a secret link to new feature called the “recovery mode”. Clicking this link will have the user enter this recovery mode, which works by placing a cookie on the current client.

When in recovery mode, plugins and themes (also referred to as “extensions”) which are causing a fatal error are paused for that client, ensuring they can work around these errors and access their admin backend as regularly. After entering recovery mode, the user needs to log in. It should be highlighted though that recovery mode itself is not tied to a specific user, but only to the cookie existing on the client.

After logging in, an admin notice will indicate that recovery mode is enabled. Furthermore, the user will be informed about which plugins/themes are currently paused due to fatal errors, and what exactly these errors are. They then have the possibility to address the issue in their preferred way:

  • They can completely deactivate the extension, e.g. when maintaining a working version of the site matters more than that extension’s functionality. This is typically a temporary solution, but provides an immediate resolution.
  • They can fix the problem if they have the technical capabilities, and afterwards resume the extension.
  • They can file a support ticket with the author of the respective extension or contact a developer, pointing out the exact error.

At any time, the user can decide to exit recovery mode, by clicking a button that permanently appears in the admin bar while in recovery mode. Exiting recovery mode will wipe the cookie from the client and thus cause all extensions to run as usual again. Keep in mind that if an extension is still broken, the fatal error will remain.

Admin backend while in recovery mode. Highlighted are the notice and the exit button in the admin bar, indicating recovery mode is active.
Admin backend while in recovery mode

The main benefit of recovery mode is to inform administrators about fatal errors on their site and allow them to still access their backend and decide what to do about the problem, rather than presenting them with the typical “white screen of death” which they cannot do anything about. It is impossible to automatically fix such errors, but recovery mode allows working around them by pausing the broken extensions. Pausing only happens for the client that is in recovery mode, and thus does not have any global implications. With a broken extension, only the user in recovery mode can access the broken areas; for the other users the site remains in a broken state until the issue has been fixed or mitigated.

Developers

There are a couple of ways that developers can integrate with the new recovery mode features:

  • Plugins that would like to enhance recovery mode can call a new function wp_is_recovery_mode() to check for whether it is active.
  • Environments can override the way that recovery mode is set up and validated if they prefer to use a different method or to purely enable it via code. A must-use plugin for example can set a constant WP_RECOVERY_MODE_SESSION_ID that needs to contain an arbitrary session ID, which will then be used to store recovery mode-specific data for that session. Having the constant available will force-enable recovery mode. However, this mechanism must be used with special care, as setting the constant unconditionally would result in recovery mode being globally enabled.
  • The template for the screen indicating that a fatal error occurred can be customized by using a php-error.php drop-in, similar to other previously existing drop-ins such as db-error.php.
  • The entire shutdown handler can be overridden by using a fatal-error-handler.php drop-in. This drop-in must return an instance of a class extending the default WP_Fatal_Error_Handler class. If that is the case, the instance will be used instead of the default one.
  • Environments that would like to disable the fatal error handler and recovery mode functionality altogether can do so by setting a WP_DISABLE_FATAL_ERROR_HANDLERconstant, typically in wp-config.php. The enabled status for the handler should be checked for by using a new function wp_is_fatal_error_handler_enabled().

Background

The fatal error recovery mode is a revised approach for what was originally the fatal error protection mechanism slated for WordPress 5.1, but then reverted due to some critical concerns. The client-specific recovery mode mitigates these concerns, so this time it is here to stay.

For further background information, please refer to the announcement post for the revised approach, the overarching Trac ticket, and generally the list of related 5.2 tickets.

#5-2, #dev-notes, #servehappy