WordPress recovery mode integration

WP Debug Toolkit (WPDT) enhances the WordPress recovery mode email with links to the standalone viewer and additional debugging context. When your site crashes, the recovery email points you to tools that work even when wp-admin is inaccessible.

What WordPress recovery mode is

WordPress 5.2 introduced recovery mode. When a fatal PHP error occurs — a plugin crashes, a theme has a syntax error, PHP runs out of memory — WordPress catches the error and takes two actions:

1. It pauses the offending plugin or theme so the admin dashboard remains accessible
2. It sends an email to the site administrator with a temporary login link that bypasses the paused code

The recovery mode email contains a time-limited URL (valid for a set period) that logs you into wp-admin with the problem code disabled. From there, you can deactivate or update the offending plugin or theme.

How WPDT enhances recovery emails

When WPDT is active and the standalone viewer is installed, the recovery mode email includes additional sections:

Standalone viewer link

The email includes a direct link to your standalone viewer URL (e.g., https://example.com/wpdebugtoolkit/). Unlike the recovery mode login link, the viewer does not depend on WordPress being functional. If wp-admin is down, the database is unreachable, or WordPress is stuck in a fatal error loop, the viewer still works because it runs as an independent application.

Viewer capabilities

The email lists what you can do in the viewer during a crash:

• Complete error logs with stack traces
• Exact file and line number
• Recent error history and patterns
• Database query performance issues
• Advanced debugging tools

Troubleshooting steps

The enhanced email includes a short list of recommended actions:

1. Visit the standalone viewer to review the error log
2. Use the recovery mode link to access wp-admin
3. Once recovered, check your error notification settings at Debug Toolkit > Settings > Notifications

Common crash causes

The email lists frequent reasons for fatal errors:

• Recently activated or updated plugin
• Theme incompatibility
• PHP version mismatch
• Memory limit exceeded

Debug information

WPDT appends a debug information block to the recovery email. This provides context for developers or support staff investigating the crash:

This block helps support teams quickly assess the debugging tools available on the affected site without logging in.

Fatal error handler drop-in

WordPress loads a fatal error handler during shutdown to catch errors that bypass normal PHP error handling. WPDT installs a custom fatal-error-handler.php drop-in that extends the default WordPress handler (WP_Fatal_Error_Handler).

The drop-in works in two stages:

1. It calls the parent WordPress handler, which processes recovery mode and sends the standard recovery email
2. It delegates to the MU-plugin’s notification handler to send a WPDT error notification

This ensures you receive both the WordPress recovery email (with WPDT enhancements) and a separate WPDT notification email with the full error details, stack trace, and rate-limiting logic.

The drop-in is installed to wp-content/fatal-error-handler.php. WordPress detects it automatically during the error handling process.