Auto-heal: recovering from a fatal plugin error

Starting with connector version 1.20.0, the Manage GPL connector ships with a WordPress fatal-error handler that prevents a crashing plugin from taking your whole site offline. When you see a "plugin auto-deactivated" notification from us, this is what happened and what to do.

How it works

The connector installs a PHP drop-in file at wp-content/fatal-error-handler.php. When any plugin on your site triggers a fatal PHP error — a type mismatch, undefined method, missing dependency, etc. — this handler catches it before WordPress shows the white-screen-of-death or the generic "There has been a critical error on this website" message.

The handler:

1. Identifies which plugin's code caused the fatal (via the PHP stack trace).
2. Deactivates that plugin, writing a record to a WordPress option.
3. Lets the request fail gracefully, but the next request loads without the offending plugin active.
4. Records the auto-deactivation event so Manage GPL's next inventory pull can surface it to you.

The result: a broken plugin update that would have taken your site down instead takes just that plugin offline, and your site stays up.

What you'll see in Manage GPL

• An email notification: "Plugin auto-deactivated on {site} — {plugin} caused a fatal error and was disabled".
• An entry in the site's Activity log tagged auto_deactivation.
• The plugin shows as inactive in the site's plugin list.

What you should do next

1. Check your site. It should be loading fine. If it isn't, restore from backup and contact support — something beyond auto-heal's scope went wrong.
2. Decide whether to investigate or roll back. Options:
   • Re-activate and debug (if you're comfortable; check error logs, maybe the fatal was a race condition).
   • Roll the plugin back to the previous version. SSH in and replace the plugin folder, or install an older version via WP-CLI.
   • Leave it deactivated until a newer version is released that fixes the bug.
3. Report to the plugin vendor. If the fatal is reproducible, the vendor wants to know. Most vendors have a support channel.

Exclusions

The handler is careful not to auto-deactivate:

• The Manage GPL connector itself — deactivating our own plugin would sever the connection and leave you locked out.
• Plugins that are network-activated on multisite — they're handled separately because a network-active plugin often has side effects that individual-site deactivation can't undo cleanly.

Disabling auto-heal

It's on by default. If you really want to turn it off (most users shouldn't), you can remove the wp-content/fatal-error-handler.php file, but it'll be recreated on the next connector update.