Out of Memory Errors

WP Debug Toolkit (WPDT) detects PHP out-of-memory (OOM) errors and sends you an email notification even though the request has fatally crashed and normal execution has stopped. This works because the WPDT MU-plugin reserves 256KB of memory at startup specifically for this purpose, freeing it the moment the shutdown handler fires so the alert can go out. To adjust your site’s memory limit, navigate to WP Debug Toolkit › Settings › PHP Settings.

What an OOM Error Looks Like

When PHP exhausts its available memory, the process terminates immediately. The entry left in debug.log looks like this:

[15-Mar-2026 14:32:10 UTC] PHP Fatal error: Allowed memory size of 268435456 bytes exhausted (tried to allocate 65536 bytes) in /wp-content/plugins/example-plugin/includes/class-import.php on line 215

The first number, 268435456, is the configured memory limit in bytes (268,435,456 bytes = 256MB). The second number, 65536, is the size of the allocation that pushed PHP past that limit. No code runs after this point. Normal execution has stopped.

Why OOM Errors Are Hard to Catch

A standard PHP error handler requires memory to execute. When a process runs out of memory, the handler cannot run because the one resource it needs is gone. Standard PHP logging still writes the entry to debug.log, but no email notification system built on wp_mail() or a regular plugin can fire afterward: there is nothing left to execute it. This is why OOM errors are uniquely difficult to surface in real time. By definition, the moment they occur, the normal error-reporting pipeline cannot respond.

How WPDT Handles OOM Errors

WPDT’s MU-plugin handles OOM errors through three connected mechanisms. They work together to turn what would otherwise be a silent crash into a notification that reaches you within seconds.

Memory Reservation

When wpdebugtoolkit-notifications.php loads at WordPress startup, before any regular plugin, WPDT reserves a dedicated block of memory:

php
// 256KB reserved at initialization -- held until a shutdown event fires
self::$memory = str_repeat( '*', 1024 * self::RESERVED_MEMORY_KB );

This reserved block sits unused while your site runs. During an OOM crash, the sequence is:

WPDT’s MU-plugin reserves 256KB at initialization.
Your site runs normally, consuming all other available memory.
Memory exhausts and PHP triggers a fatal shutdown.
The shutdown handler fires and immediately releases the reserved block: self::$memory = null;
The freed 256KB gives the handler enough memory to build and send the notification email.

This mechanism is automatic and does not require you to configure any additional settings.

Notification Delivery

After releasing the reserved memory, the shutdown handler calls error_get_last() to retrieve the error details. It then builds a notification email containing the Error Type, Message, File, Line, Time, and Request Details.

For recoverable fatal errors, which is the category that includes OOM events, WPDT intercepts WordPress’s own recovery email, suppresses it, and sends its own version in its place.

This gives WPDT control over the email content and format while still using WordPress’s recovery URL, which carries the extension tracking needed to safely deactivate the offending plugin or theme. The email includes a Recovery URL that gives you access to WordPress admin safely, and a direct link to the standalone Viewer App.

WPDT sends the email via wp_mail(). If wp_mail() fails because WordPress is in a broken state at the time of the crash, WPDT falls back automatically to PHP’s native mail() function.

Error Hash Normalization

OOM error messages include a variable component: the “tried to allocate X bytes” portion changes with every crash because the allocation size differs. Without normalization, each crash from the same plugin would generate a unique hash, bypass rate limiting, and flood your inbox.

WPDT strips the allocation size from any message beginning with “Allowed memory” before hashing it, so repeated crashes from the same file and line share a single error hash. Rate limiting then applies to the error source rather than to each individual crash.

✅ Key Guarantees

WPDT sends OOM notifications even when the request has fatally crashed and normal execution has stopped.
The 256KB memory reservation releases at the very start of the shutdown handler, before any email-building code runs.
If wp_mail() fails during shutdown, WPDT falls back to PHP’s native mail() function automatically.
Repeated OOM crashes from the same file and line share one error hash, so rate limiting targets the error source rather than each individual crash event.

Common Causes

Most OOM errors on WordPress sites trace back to one of these events:

Importing large datasets: CSV imports, WooCommerce product imports, and media library bulk operations load large amounts of data into memory in a single request.
Plugins loading entire datasets without pagination: Querying all posts, all users, or all orders at once is a common cause in plugins not designed for large databases.
Image processing: Resizing or converting large images with GD or Imagick can require several times the image’s file size in available memory.
Recursive or deeply nested operations: Plugins that call themselves recursively without a depth limit can consume memory rapidly.
Memory leaks in long-running processes: WP-Cron jobs and background workers that accumulate memory across many iterations can exhaust the limit even when individual iterations appear safe.

Prevention

Increase the Memory Limit

Set WP_MEMORY_LIMIT in wp-config.php to give WordPress more headroom:

php
// Set in wp-config.php — may not be able to exceed the server's PHP memory_limit in php.ini
define( 'WP_MEMORY_LIMIT', '256M' );

On most hosts, WordPress applies WP_MEMORY_LIMIT via ini_set(), which can raise memory above the php.ini default. If your host locks memory or disables ini_set(), however, the php.ini value becomes a hard ceiling that WP_MEMORY_LIMIT cannot override.

On hosts where wp-config.php is writable, you can also set this value from WP Debug Toolkit › Settings › PHP Settings › Memory Limit (wp-config.php)

Identify the Source

The file path in the OOM error message tells you what to investigate:

/wp-content/plugins/plugin-name/ points to a specific plugin.
/wp-content/themes/theme-name/ points to your active theme.
/wp-includes/ or /wp-admin/ points to WordPress core, which is a rare cause of OOM errors.

Open the error entry in the WPDT Error Log Viewer App to inspect the responsible file directly.

Monitor Trends

Check whether recurring OOM errors correlate with specific actions such as imports, scheduled cron jobs, or particular page loads. WPDT keeps a 7-day alert history, including suppressed notifications. Because WPDT normalizes OOM messages before hashing, repeated crashes from the same file and line share one signature in the history log, making it straightforward to confirm whether one source drives multiple incidents.

Frequently Asked Questions

Why Does WPDT Need a MU-Plugin to Send OOM Notifications?

A regular WordPress plugin loads after WordPress finishes initializing and after other plugins load. If a plugin earlier in the sequence causes a fatal error, a standard plugin may never load at all. The MU-plugin wpdebugtoolkit-notifications.php loads first in the WordPress boot sequence, which means its shutdown handler is registered before any regular plugin code runs. WPDT can therefore capture and report fatal errors that occur in plugins that load afterwards.

Does WPDT Always Send a Notification When a Site Runs Out of Memory?

Not always. If the error hash matches a recent notification within the active rate limit window, WPDT suppresses the duplicate and records it in the alert history instead of sending a second email. If the global hourly cap for fatal errors has been reached, WPDT logs the skipped notification rather than sending it. Both suppressed and sent notifications appear in the 7-day alert history.

How Do I Stop Getting Repeated OOM Notifications From the Same Plugin?

Open the alert history and check whether the repeated notifications share the same error hash. If they do, rate limiting will suppress further duplicates within the cooldown window automatically. If the volume is still too high, the per-error cooldown window or the global hourly cap may need adjustment. See Rate Limiting and Alert History.