WordPress Critical Error: Developer Troubleshooting Guide

“There has been a critical error on this website” is WordPress’s safe presentation of a fatal PHP error. The visible message is intentionally generic. The actual cause is usually recorded in the recovery email, PHP error log, web-server journal, or a temporary WordPress debug log.

Protect the current evidence before changing plugins, themes, PHP versions, or files.

Stabilize the incident

Record:

• The first known failure time.
• The affected URLs and whether /wp-admin/ works.
• The last deployment, update, configuration, or content action.
• PHP, WordPress, theme, and plugin versions.
• Whether all users or only one workflow is affected.

If a recent release clearly caused the incident and you have a tested rollback, restore the last known-good release while preserving logs. Do not overwrite the only copy of the failing code before finding the cause.

Create a database and file backup before manual repair when the site state is still changing.

Use WordPress Recovery Mode

WordPress Recovery Mode can detect some fatal PHP errors during normal page loads and send an administrator a special login link. Inside that session, WordPress pauses the faulty plugin or theme for the recovery session so you can investigate.

Confirm the email is legitimate and the domain is correct before opening the link. If the message never arrives, check the administrative email route and mail delivery, then continue through server access.

Recovery Mode is a troubleshooting path, not proof that the highlighted component is the root architectural cause. A plugin may trigger a fatal condition exposed by memory exhaustion or a PHP-version change.

Read the real fatal error

Start with the PHP-FPM and web-server logs:

sudo journalctl -u php8.3-fpm --since "30 minutes ago"
sudo tail -n 100 /var/log/nginx/error.log

Paths and service names vary. On managed hosting, use its PHP error-log viewer.

When needed, enable WordPress file logging temporarily in wp-config.php, before the “stop editing” line:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
@ini_set('display_errors', 0);

Reproduce the error once, then inspect wp-content/debug.log. Disable debug mode after diagnosis and remove or protect the log; it can contain filesystem paths, query fragments, customer data, or secrets.

Read the first relevant fatal error and stack trace, not dozens of later warnings. Note the exception type, message, file, and line.

Interpret common failure patterns

Typical messages suggest a direction:

• Call to undefined function or undefined method: incompatible plugin, theme, dependency, or partial deployment.
• Cannot redeclare: duplicate code loading or conflicting versions.
• Allowed memory size exhausted: runaway work, oversized query/result, image processing, or a limit that may be too low.
• Uncaught TypeError: incompatible data or stricter PHP behavior.
• Failed opening required: missing vendor, theme, plugin, or core file.
• Parse error: corrupted file, incomplete update, or syntax incompatible with the active PHP version.

Increasing the PHP memory limit can restore service for a legitimate workload, but it should not be the first and only response. Find what consumed the memory.

Isolate plugins safely

If wp-admin works, deactivate the suspected plugin and retest. On a production store or membership site, understand the business effect before disabling payment, access, caching, or security components.

With WP-CLI:

wp plugin list --status=active
wp plugin deactivate suspected-plugin

If WordPress cannot boot, rename only the suspected plugin directory:

mv wp-content/plugins/suspected-plugin \
   wp-content/plugins/suspected-plugin.disabled

Renaming the entire plugins directory can restore access, but it removes evidence about which component failed and may break critical workflows. Use it only as a deliberate broad isolation step, then restore the directory name and reactivate plugins one at a time in a staging copy.

Do not delete the plugin first; you may need its exact failing version for analysis and rollback.

Test the active theme

If the stack trace points to the active theme or child theme, switch to an installed default theme on staging:

wp theme list
wp theme activate twentytwentyfive

Confirm the default theme is present before activating it. If the error disappears, compare recent theme changes, parent-theme compatibility, hooks, and PHP requirements.

Never edit a vendor or parent theme directly as a permanent fix. Use a child theme or a maintained patch so updates do not erase the repair.

Check PHP and deployment compatibility

Compare the active PHP version and extensions with the requirements of WordPress and every critical plugin:

php -v
php -m
wp core version

Remember that CLI PHP can differ from PHP-FPM. Confirm the web runtime through hosting controls or FPM configuration.

After a partial update or deployment, check for missing Composer dependencies, incorrect ownership, full disks, and mixed release files. Verify WordPress core checksums:

wp core verify-checksums

A checksum mismatch is evidence to investigate; customized, localized, or managed files may need context. Replace core files from a trusted matching release, never from an unknown archive.

If Nginx begins returning a boundary error because PHP-FPM is crashing, follow the 502 Bad Gateway guide alongside the PHP fatal analysis.

Verify the repair

After the targeted rollback or fix:

1. Clear only relevant caches.
2. Test the original failing URL and action.
3. Test wp-admin, login, forms, checkout, scheduled tasks, and API endpoints relevant to the component.
4. Confirm no new fatal errors enter the logs.
5. Re-enable paused components only after compatibility is proven.
6. Disable temporary debug logging.
7. Document the cause, affected version, repair, and prevention.

Run the same check in staging with production-like PHP and data volume before applying an upgrade again.

Common mistakes and prevention

Avoid randomly disabling every plugin, editing production files without a backup, displaying PHP errors to visitors, raising memory indefinitely, deleting the failing version, or updating multiple components at once during the incident.

Prevent recurrence with staged updates, immutable releases, tested rollback, uptime and log monitoring, version compatibility checks, and backups that are regularly restored in a test environment. For performance work after recovery, use the WordPress LCP guide to measure bottlenecks rather than stacking emergency plugins.

Frequently asked questions

What if the WordPress Recovery Mode email never arrives?

Use the hosting control panel, SSH, SFTP, or WP-CLI to inspect logs and isolate the named component. Also verify the configured administrator address and mail delivery after service is stable.

Should I deactivate every plugin first?

Only as a deliberate emergency isolation step. The stack trace and recent change history usually support a narrower test that preserves evidence and avoids disabling unrelated business functions.

Official references

• WordPress Recovery Mode
• Debugging in WordPress
• WordPress troubleshooting FAQ

Have a question about this guide or an idea for a technical collaboration? Contact Bakry through the Dev Hub.