What happens when WordPress hits a fatal error

A WordPress fatal error happens when PHP encounters a problem serious enough that it cannot continue executing the current request. When this happens, WordPress may stop rendering the page, display a critical error message, trigger Recovery Mode or return an incomplete response depending on where the failure occurred.

Fatal errors are different from warnings and notices. A warning may allow the request to continue, while a fatal error stops execution at the point where the problem occurs.

For a WordPress site, that can mean a broken frontend page, an inaccessible admin screen, a failed AJAX request, a REST API error or an email notifying the site administrator that WordPress detected a technical problem.

In this guide, we will look at what actually happens when WordPress encounters a fatal error, how WordPress and PHP handle the failure, what Recovery Mode does and how to troubleshoot the problem without making the situation worse.

What is a fatal error in WordPress?

A WordPress fatal error is usually a PHP error that stops the current request completely.

Common causes include:

• calling a function that does not exist;
• instantiating a class that cannot be found;
• declaring the same function or class twice;
• calling a method on an object that is null or otherwise invalid;
• using incompatible code after a PHP upgrade;
• exceeding the PHP memory limit;
• loading incompatible plugin or theme code;
• triggering an uncaught error or exception;
• syntax or execution problems inside custom code.

The exact behavior depends on the PHP version, the type of error and where in the WordPress request the failure occurs.

PHP itself defines several categories of errors with different severity levels. For the underlying PHP error model, see the PHP error constants documentation.

What happens when PHP hits a fatal error?

PHP processes a request by executing code in sequence.

If it reaches an unrecoverable error, execution stops.

Imagine a simplified request:

Load WordPress
Load plugins
Load theme
Run query
Render header
Render content
Render footer

If a fatal error occurs while rendering the content, PHP does not continue normally to the remaining steps.

The request terminates at that point.

This means code scheduled to run later in the request may never execute.

A fatal error affects the current request

A PHP fatal error does not normally mean the entire WordPress installation permanently stops existing.

It means the request that encountered the problem cannot finish normally.

For example, a fatal error might affect:

• one frontend URL;
• every frontend URL;
• only wp-admin;
• one specific admin screen;
• an AJAX request;
• a REST API endpoint;
• a scheduled task;
• a WP-CLI command.

The scope depends on which code triggers the failure and when that code runs.

Why WordPress may show “There has been a critical error on this website”

On normal web requests, WordPress can detect certain fatal PHP errors and display a generic message instead of exposing the raw PHP error to visitors.

The message commonly looks like:

There has been a critical error on this website.

This message is intentionally generic.

Displaying the complete PHP error publicly could reveal sensitive technical information such as:

• filesystem paths;
• plugin names;
• theme structure;
• class names;
• server configuration;
• internal application details.

WordPress handles supported fatal errors through its fatal error protection system. The relevant core implementation is documented in WP Fatal Error Handler.

The public message therefore tells the visitor very little while the detailed error should be investigated through logs or debugging tools.

The critical error message is not the actual error

The message:

There has been a critical error on this website.

is a symptom, not the underlying cause.

The actual PHP error might be something such as:

PHP Fatal error:
Uncaught Error: Call to undefined function example_function()

or:

PHP Fatal error:
Allowed memory size of 268435456 bytes exhausted

To fix the problem, you need the detailed error information rather than the generic WordPress screen.

What is WordPress Recovery Mode?

WordPress includes a Recovery Mode designed to help administrators regain access when certain plugin or theme errors cause fatal failures.

When WordPress detects an eligible fatal error, it can generate a special recovery link and send it to the site’s administration email address.

The recovery link allows an administrator to enter a temporary recovery session.

Inside Recovery Mode, WordPress can pause the component responsible for the detected error for that administrator’s session, allowing access to the dashboard so the problem can be investigated.

The internal Recovery Mode system is documented in the official WP Recovery Mode reference.

Recovery Mode does not permanently fix the problem

Recovery Mode is a troubleshooting mechanism.

It does not repair broken PHP code automatically.

Its purpose is to help you regain enough access to:

• identify the failing plugin or theme;
• deactivate the problematic component;
• update it;
• replace it;
• fix custom code;
• restore a working version.

The actual cause still needs to be corrected.

What does WordPress mean by a paused plugin or theme?

During Recovery Mode, WordPress may temporarily pause the extension associated with the detected fatal error for the recovery session.

This allows the administrator to access pages that would otherwise trigger the same failure repeatedly.

That pause is not the same as permanently uninstalling the plugin or deleting the theme.

It exists to provide a safe administrative path while troubleshooting.

What happens to normal visitors during Recovery Mode?

Recovery Mode is specific to the administrator using the special recovery session.

It does not automatically mean all visitors receive the same temporary configuration.

The site may still show the fatal error to ordinary visitors until the actual issue is fixed.

This is why Recovery Mode should be used to diagnose and resolve the problem rather than treated as a permanent operating state.

What does the WordPress recovery email contain?

When WordPress can identify a fatal error associated with a plugin or theme, the administrator email may contain information about the affected component and a special Recovery Mode link.

The message may help identify:

• which plugin or theme triggered the error;
• which page was affected;
• basic error information;
• the recovery login URL.

Do not publish the recovery link publicly.

It is intended as a temporary administrative recovery mechanism.

What if the recovery email never arrives?

Recovery Mode depends partly on WordPress being able to send email successfully.

The message may fail to arrive because of:

• incorrect administrator email configuration;
• mail delivery problems;
• SMTP issues;
• spam filtering;
• hosting restrictions;
• the failure occurring in a context where recovery handling cannot complete normally.

You should therefore never rely on Recovery Mode email as the only possible way to regain administrative access.

Fatal error vs warning vs notice

Not every PHP problem stops WordPress.

A useful simplified distinction is:

Notice
Execution usually continues

Warning
Execution often continues

Fatal error
Execution stops

Modern PHP also has other error and exception types, so the complete error model is more detailed than this simple classification.

The important practical difference is whether PHP can continue processing the request.

Fatal errors can occur before WordPress fully loads

Some fatal errors happen very early in the bootstrap process.

For example, a problem might occur while WordPress is loading:

• must-use plugins;
• regular plugins;
• theme code;
• configuration files;
• autoloaded classes.

If the failure occurs early enough, parts of WordPress may never initialize.

This can affect which recovery or logging mechanisms are available.

Fatal errors during plugin loading

WordPress loads active plugins during the bootstrap process.

If a plugin triggers a fatal error while being loaded, the request may stop before WordPress reaches the theme or page rendering stage.

Common causes include:

• missing dependencies;
• incompatible PHP syntax;
• duplicate function names;
• duplicate class names;
• incorrect autoloading;
• code assuming another plugin has already loaded.

Load order matters when plugin code depends on hooks or functionality registered by another component. See WordPress hooks: plugins_loaded vs. init for a closer look at two important points in the WordPress bootstrap sequence.

Fatal errors during theme loading

A theme can also trigger fatal errors.

This may happen inside:

• functions.php;
• template files;
• theme includes;
• custom classes;
• template functions.

If the error only occurs when rendering specific templates, some pages may continue working while others fail.

A fatal error can affect only one page

Not every fatal error takes down the entire website.

Suppose a broken function is called only on a product template.

The homepage might work normally while product pages fail.

Similarly, custom code attached to:

admin_init

might break the WordPress dashboard while leaving the public frontend unaffected.

The affected area gives you an important clue about when the failing code runs.

Fatal errors can affect AJAX requests

WordPress performs many administrative and frontend actions through AJAX.

If an AJAX callback triggers a fatal error, the visible page may remain loaded while the background request fails.

Symptoms can include:

• spinners that never finish;
• buttons appearing unresponsive;
• failed media uploads;
• settings that do not save;
• generic JavaScript errors;
• HTTP 500 responses in browser developer tools.

In these cases, inspect both the browser network request and the server-side PHP logs.

Fatal errors can affect the REST API

A plugin or theme can also trigger a fatal error during a WordPress REST API request.

This may break:

• the block editor;
• headless frontends;
• external integrations;
• mobile applications;
• custom JavaScript interfaces.

The normal website may still appear functional while the REST API returns errors.

For a broader understanding of how much of modern WordPress can rely on these endpoints, see What depends on the WordPress REST API.

Fatal errors can happen during WP-Cron

Scheduled tasks run through WordPress can also fail with fatal errors.

A visitor may never see a critical error page because the failure happens during background processing.

Instead, you might notice:

• scheduled emails not being sent;
• imports no longer running;
• backups failing;
• scheduled posts not publishing;
• cleanup jobs stopping.

This is one reason server logs matter even when the frontend appears healthy.

Fatal errors can happen during WP-CLI commands

If WordPress is being managed through WP-CLI, a fatal error may appear directly in the terminal.

For example:

wp plugin list

can fail if WordPress cannot bootstrap because an active plugin triggers a fatal error.

WP-CLI supports options such as --skip-plugins and --skip-themes on many commands, which can be useful when isolating a broken component. See the official WP-CLI plugin list documentation.

In some troubleshooting situations, WP-CLI can skip loading regular plugins or the active theme so WordPress can bootstrap sufficiently for administrative commands. Must-use plugins may still load and should be investigated separately if the failure occurs very early.

What does HTTP 500 mean?

Fatal PHP errors frequently result in an HTTP 500 response.

An HTTP status such as:

500 Internal Server Error

means the server could not complete the request successfully.

However, HTTP 500 is not specific to WordPress fatal errors.

Other server problems can produce the same status, including:

• web server configuration errors;
• permission problems;
• PHP configuration failures;
• application exceptions;
• upstream service failures.

Use logs to determine the actual cause.

What is the WordPress debug log?

WordPress can write PHP and WordPress debugging information to a log file when debugging is configured appropriately.

A common development configuration includes:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

With the standard configuration, debug output can be written to:

wp-content/debug.log

depending on the environment and WordPress configuration.

The official WordPress debugging documentation explains the relationship between WP_DEBUG, WP_DEBUG_LOG and WP_DEBUG_DISPLAY.

Do not display PHP errors publicly on production

On a production website, displaying raw PHP errors directly to visitors is generally undesirable.

A detailed error can reveal information such as:

/var/www/example.com/public/wp-content/plugins/example/plugin.php

This tells an attacker:

• the server path;
• the plugin involved;
• part of the site structure.

Prefer logging detailed errors privately while showing visitors a generic error response.

Where else can fatal errors be logged?

Depending on the hosting environment, errors may appear in:

• PHP error logs;
• PHP-FPM logs;
• Nginx error logs;
• Apache error logs;
• hosting dashboards;
• application monitoring platforms;
• WordPress debug logs.

The WordPress debug log is useful, but it is not necessarily the only or most complete source of information.

How to read a WordPress fatal error

A typical fatal error contains several useful pieces of information.

For example:

PHP Fatal error:
Uncaught Error: Call to undefined function example_function()
in /var/www/html/wp-content/plugins/example/plugin.php:42

This tells you:

• the error type;
• the immediate reason;
• the file where the failure occurred;
• the line number.

A stack trace may also show the sequence of function or method calls that led to the failure.

The file listed in the error is not always the real cause

If the error points to a plugin file, that plugin may indeed contain the bug.

But the root cause could also be elsewhere.

For example:

• another plugin may have failed to load a dependency;
• a theme may call the plugin incorrectly;
• custom code may pass invalid data;
• a PHP upgrade may expose an incompatibility;
• a class may have been renamed in an update.

Treat the error location as evidence, not automatic proof of responsibility.

What is a stack trace?

A stack trace shows the chain of function or method calls that led to the error.

A simplified trace might look like:

#0 plugin.php(120): example_process()
#1 class-wp-hook.php(324): example_callback()
#2 plugin.php(517): WP_Hook->apply_filters()
#3 index.php(17): require(...)
#4 {main}

The stack trace can help identify how WordPress reached the failing code.

It is often more useful than looking only at the final line number.

Fatal error: undefined function

A common fatal error is:

Call to undefined function example_function()

This means PHP attempted to execute a function that was not available at that moment.

Possible causes include:

• the required file was not included;
• a dependency plugin is inactive;
• the code runs too early;
• the function was removed or renamed;
• a plugin update changed the API.

When the problem is related to WordPress load order, check whether the function is being called before the plugin, file or hook that defines it has finished loading.

Fatal error: class not found

Another common error is:

Class "Example_Class" not found

This often indicates:

• autoloading failure;
• missing dependency;
• incorrect namespace;
• wrong file path;
• code running before the class is available.

Fatal error: cannot redeclare function

PHP can also stop when the same function is declared more than once.

For example:

Cannot redeclare example_function()

This can happen when:

• two plugins use the same global function name;
• a file is included twice incorrectly;
• custom code duplicates existing plugin code.

Using unique prefixes, namespaces and proper loading practices helps reduce this risk.

Fatal error: memory exhausted

A WordPress request can also fail when PHP exceeds its configured memory limit.

A typical message is:

Allowed memory size of 268435456 bytes exhausted

This does not necessarily mean the site simply needs a permanently higher memory limit.

Possible causes include:

• very large queries;
• processing huge images;
• infinite loops;
• loading very large datasets;
• poorly optimized plugins;
• memory leaks in application logic.

Increasing memory may hide the symptom without fixing the underlying problem.

If the failure appears connected to expensive administration requests or excessive background work, see Reducing WordPress admin server load for the broader performance side of the problem.

Fatal errors after a PHP upgrade

Upgrading PHP can expose outdated plugin, theme or custom code.

Code that worked under an older PHP version may fail because of:

• removed functionality;
• stricter type handling;
• deprecated behavior becoming unsupported;
• library incompatibilities;
• old syntax.

Test PHP upgrades in a staging or otherwise isolated environment before applying them to important production websites.

Fatal errors after a WordPress update

A WordPress core update can also expose plugin or theme compatibility issues.

The core update itself may be correct while custom code relies on behavior that has changed.

After an error following an update, check:

• WordPress core version;
• plugin versions;
• theme version;
• PHP version;
• recent changelogs;
• custom code compatibility.

A repeatable staging-first process helps identify compatibility failures before the live environment is changed. See Building a staging-first WordPress update workflow.

Fatal errors after a plugin update

If the problem begins immediately after a plugin update, that plugin becomes an obvious investigation target.

However, the failure may result from interaction with another component.

For example:

Plugin A update
    ↓
Function signature changes
    ↓
Custom Plugin B still calls old function
    ↓
Fatal error

The updated plugin may have exposed an outdated dependency elsewhere.

This is one reason plugin maintenance should include an assessment of compatibility and dependency risk rather than treating every available update as an isolated change. See The risks of not updating WordPress plugins for the other side of that maintenance decision.

How to troubleshoot a WordPress fatal error

A safe troubleshooting process should change as little as possible at once.

Step 1: Record what happened

Before changing anything, note:

• the failing URL;
• the visible message;
• when the problem started;
• what changed immediately before it;
• whether frontend and admin are both affected.

Step 2: Check the error logs

Find the actual PHP error and identify the file, line and stack trace.

Step 3: Check recent changes

Look for:

• plugin updates;
• theme updates;
• WordPress updates;
• PHP changes;
• new snippets;
• custom deployments.

Step 4: Use Recovery Mode if available

If WordPress sends a valid Recovery Mode link, use it to access the dashboard and inspect the affected component.

Step 5: Isolate the failing component

Deactivate or bypass the suspected plugin, theme or custom code in a controlled way.

Step 6: Reproduce the error

Confirm whether the failure disappears when the suspected component is removed from the request.

Step 7: Fix the cause

Update, patch, replace or correct the faulty code rather than relying permanently on the workaround.

Do not deactivate every plugin immediately

Disabling all plugins can sometimes help confirm whether the problem is plugin-related, but it destroys useful diagnostic information if used as the first reaction.

If you know the error points directly to one plugin, start there.

If the cause is unknown, use systematic isolation rather than random deactivation.

Changing twenty components simultaneously ensures that if the problem disappears, you have learned almost nothing about why.

How to deactivate a broken plugin without wp-admin

If the dashboard is inaccessible, an authorized administrator can sometimes deactivate a plugin through the filesystem.

WordPress plugins are normally stored in:

wp-content/plugins/

Renaming the directory of a specific plugin can prevent WordPress from loading it.

For example:

example-plugin
↓
example-plugin-disabled

Use this carefully and only when you know which component you are isolating.

Use WP-CLI to isolate plugins

If you have shell access, WP-CLI can also help diagnose plugin-related failures.

For example, you can deactivate a plugin with:

wp plugin deactivate example-plugin

In some troubleshooting situations, WP-CLI can skip loading regular plugins or the active theme so WordPress can bootstrap sufficiently for administrative commands. Must-use plugins may still load and should be investigated separately if the failure occurs very early.

This can be particularly useful when the normal dashboard cannot load.

What if the active theme causes the fatal error?

If the active theme is responsible, switch to a known working theme during troubleshooting.

On production, do this carefully because changing themes can affect:

• layout;
• menus;
• widgets;
• template rendering;
• custom functionality.

Testing the change outside production is preferable whenever possible.

Custom snippets can cause fatal errors too

Code snippet plugins and custom PHP modules can introduce exactly the same fatal errors as traditional plugins.

Examples include:

• syntax errors;
• undefined functions;
• duplicate declarations;
• incorrect hooks;
• missing classes;
• incompatible PHP code.

Custom snippets should therefore have a safe recovery path.

Why safe snippet execution matters

A PHP snippet manager should ideally avoid turning one bad snippet into a completely inaccessible WordPress dashboard.

Protective mechanisms can include:

• syntax validation;
• controlled execution;
• error trapping where possible;
• safe mode;
• automatic disabling of problematic snippets.

Fatal errors cannot always be handled like ordinary return values, so recovery architecture matters.

When PHP has been generated automatically or copied from an external source, review it with the same care as handwritten production code. See Reviewing AI-generated PHP before activating it for a dedicated pre-activation review process.

Do not edit production PHP blindly

When a fatal error appears, editing the affected PHP file directly on production can introduce new syntax or logic problems.

A safer workflow is:

1. capture the original error;
2. create a backup;
3. reproduce the issue outside production when possible;
4. edit under version control;
5. test the fix;
6. deploy the corrected code.

A syntax error is different from a runtime fatal error

A syntax error prevents PHP from parsing the code correctly.

For example:

if ( $enabled {
    do_something();
}

contains invalid PHP syntax.

A runtime error instead occurs after PHP successfully parses the file and begins executing it.

For example:

missing_function();

is syntactically valid PHP but may fail at runtime if that function does not exist.

Why staging is important for fatal error prevention

Many fatal errors can be caught before production if updates and custom code changes are tested in staging.

A useful staging workflow includes:

• matching the production PHP version;
• matching important plugins;
• matching the active theme;
• testing WordPress updates;
• checking error logs;
• testing critical workflows.

Staging cannot eliminate every production problem, but it drastically reduces the number of surprises introduced intentionally by maintenance work.

For a repeatable update-oriented approach, see Building a staging-first WordPress update workflow.

Backups do not prevent fatal errors

A backup does not stop bad code from causing a fatal error.

It gives you a recovery path afterward.

Before major changes, maintain backups of:

• the database;
• plugins;
• themes;
• uploads;
• custom configuration.

For deployment-related failures, version control can also make rollback much faster.

More importantly, do not assume a backup is usable merely because a backup file exists. See How to test a WordPress backup restore for the recovery side of the process.

When should you restore a backup?

Restoring the entire site is not always the first or best response to one broken plugin.

A targeted rollback may be preferable when:

• one plugin update caused the problem;
• one theme release introduced the error;
• one custom deployment failed.

A full backup restore is more appropriate when the scope of the damage is larger or the current state cannot be repaired safely.

Monitor errors even after the site appears fixed

After correcting the visible problem, continue checking logs.

A fatal error may occur only under certain conditions, such as:

• specific user roles;
• scheduled tasks;
• specific products;
• large uploads;
• particular API requests;
• rare admin actions.

A homepage loading successfully does not prove every application path is healthy.

Common WordPress fatal error mistakes

1. Assuming the critical error screen explains the problem

The useful information is normally in the underlying PHP error and stack trace.

2. Enabling public error display on production

Log errors privately instead of exposing server details to visitors.

3. Disabling every plugin immediately

Change one logical variable at a time whenever possible.

4. Increasing the PHP memory limit without investigating

Memory exhaustion can be a symptom of inefficient code rather than an insufficient server limit.

5. Ignoring Recovery Mode

Recovery Mode can provide a safe administrative entry point for supported fatal errors.

6. Editing production files without a backup

A rushed fix can create a second problem before the first is understood.

7. Assuming the file named in the error is automatically responsible

Dependencies and calling code may be the real source of the failure.

8. Testing only the homepage after fixing the error

Check the workflow that originally triggered the failure and other related paths.

WordPress fatal error troubleshooting checklist

• Record the exact error message.
• Note which URL or action triggers the problem.
• Check whether frontend and admin are both affected.
• Review PHP and server error logs.
• Check wp-content/debug.log when debugging is configured.
• Identify the file and line reported by PHP.
• Read the stack trace.
• Review recent plugin updates.
• Review recent theme updates.
• Review WordPress core updates.
• Review PHP version changes.
• Review recent custom code changes.
• Use Recovery Mode if WordPress provides it.
• Isolate the suspected component.
• Avoid changing multiple unrelated components simultaneously.
• Create a backup before major remediation.
• Use staging when possible.
• Test the exact action that previously failed.
• Review logs after the fix.
• Document the root cause.

Preventing WordPress fatal errors

You cannot guarantee that a WordPress website will never encounter a fatal error, but good maintenance substantially reduces the risk.

Useful practices include:

• keeping WordPress core maintained;
• keeping plugins and themes maintained;
• removing abandoned dependencies;
• testing PHP upgrades;
• using staging;
• maintaining backups;
• using version control for custom code;
• monitoring logs;
• avoiding untested PHP snippets on production;
• documenting custom dependencies.

Keeping plugins maintained also reduces the chance of compatibility failures accumulating across WordPress and PHP upgrades. See The risks of not updating WordPress plugins for the broader maintenance implications.

How TheOneWP helps with fatal error recovery

Fatal errors are particularly important when working with custom PHP snippets because one incorrect snippet can potentially interrupt WordPress execution.

TheOneWP includes a Snippet Manager designed to provide a safer way to manage custom HTML, CSS, JavaScript and PHP snippets inside WordPress.

For PHP snippets, the goal is not simply to execute arbitrary code and hope the dashboard survives.

The module includes protective handling so problematic PHP snippets can trigger a safer recovery path instead of unnecessarily turning a coding mistake into a permanent WordPress lockout.

This does not make invalid PHP correct, and it does not replace backups, staging or proper testing.

It does make recovery an intentional part of the snippet workflow, which is considerably preferable to discovering after deployment that your emergency procedure consists of renaming files over SSH.

Final thoughts on WordPress fatal errors

A WordPress fatal error means PHP encountered a problem serious enough to stop the current request.

The visible result may be a critical error page, HTTP 500 response, broken admin screen, failed AJAX action, REST API failure or background task that silently stops working.

WordPress Recovery Mode can help administrators regain dashboard access when certain plugin or theme failures are detected, but it does not fix the faulty code automatically.

The most useful diagnostic information normally comes from PHP error logs, WordPress debugging output and the stack trace showing where execution failed.

When troubleshooting, avoid making many changes at once. Identify the affected request, inspect the actual error, review recent changes and isolate the failing plugin, theme or custom code systematically.

Then fix the root cause rather than merely hiding the symptom.

Fatal errors are unpleasant, but they are usually understandable once the actual PHP error is available. The generic “critical error” screen is merely WordPress’s polite way of saying that something underneath has fallen over and would prefer not to discuss the details in public.