How to read a WordPress fatal error (and stop guessing)

At some point every WordPress site greets you with a blank page or the line “There has been a critical error on this website.” Both tell you the same useless thing: something broke. Neither tells you what. So people start guessing, switching off plugins one at a time and hoping the site comes back.

You do not have to guess. Behind that polite message there is a real PHP error with a file, a line, and a description of exactly what went wrong. Once you know where it lives and how to read it, most fatal errors take minutes instead of an afternoon.

First, turn the error back on

WordPress hides the actual error from visitors on purpose, which is correct. You do not want a stack trace on your homepage. But you need to see it, and the switch lives in wp-config.php. Add these lines above the comment that says “stop editing”:

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

That combination is the safe one for a live site. WP_DEBUG turns error reporting on, WP_DEBUG_LOG writes errors to a file at wp-content/debug.log instead of the screen, and WP_DEBUG_DISPLAY set to false keeps them out of sight of visitors. Reproduce the error, then open debug.log. The newest lines at the bottom are yours.

The anatomy of the message

A PHP error has a predictable shape. A typical fatal line looks like this:

PHP Fatal error: Uncaught Error: Call to undefined function get_field()
  in /wp-content/plugins/my-plugin/render.php:42

Read it in pieces. “Fatal error” is the severity, meaning the script stopped dead. A Warning or a Notice would not stop it, so those are worth fixing but they are not what caused your white screen. “Call to undefined function get_field()” is what happened. “/wp-content/plugins/my-plugin/render.php” is the file, and “:42” is the exact line. That one line already tells you the culprit is a plugin called my-plugin, and that it reached for a function that does not exist.

Reading the stack trace

Under the error you will often see a stack trace, a numbered list starting at #0. It looks intimidating and it is actually a gift. It is the chain of calls that led to the crash, most recent first. #0 is the last thing that ran before everything fell over, and as you read down the numbers you walk back through what called what.

You do not need to understand every line. You are scanning for one thing: the first file path that belongs to a plugin or a theme. Core WordPress files (the ones in wp-includes or wp-admin) are rarely the real cause. The moment you see wp-content/plugins/something or wp-content/themes/something, you have found who to blame.

The usual suspects

Most fatal errors fall into a few buckets, and the message tells you which one.

“Call to undefined function” almost always means a plugin expected something that is not there. A common version is one plugin depending on another that got deactivated, or a theme built for a plugin you have not installed. The get_field() in the example belongs to Advanced Custom Fields, so if ACF is switched off, everything that uses it breaks at once.

“Allowed memory size of N bytes exhausted” is the site running out of memory, usually from a heavy plugin or a large import. You can raise the ceiling with define('WP_MEMORY_LIMIT', '256M') in wp-config, but if it keeps climbing, something is using too much and raising the limit only delays the crash. The real fix is finding what.

“Cannot redeclare function” or “Class not found” usually means two plugins clashing, or a half finished update that left files in a mismatched state. “syntax error, unexpected” almost always means someone edited a PHP file directly and left a typo. If it happened right after you touched a file, that is your answer.

When you cannot even log in

If the error is bad enough that it locks the admin out too, WordPress has a safety net. Since version 5.2 it emails the site admin address a “recovery mode” link whenever a fatal error happens. That link logs you in with the broken plugin or theme paused, so you can deactivate it and get back in. Check that inbox before you panic, because it is often faster than anything else.

The problem with finding out by hand

Everything above works, but it has one weakness: it only happens after you go looking. The error sat in debug.log for however long before you thought to open it, and debug.log only exists if you turned it on ahead of time. Worse, one real bug can write the same error thousands of times and bury everything else.

This is the part WPPulse handles for you. It captures PHP errors as they happen, with the full stack trace, the file and line, and the request context (the URL and method that triggered it), so you are not reconstructing the scene from a log file. It fingerprints each error and groups the duplicates, so one bug is one entry with a count instead of ten thousand lines. And if an error you already fixed comes back, it flags the regression, which is the clearest sign that a recent change reopened an old problem. You can see how it works at wp-pulse.app.

The short version

A white screen is not a dead end. It is a message with the details hidden. Turn on logging, find the error in debug.log, and read it in pieces: severity, message, file, line. Follow the stack trace down to the first plugin or theme path and you have your culprit. Most of the time the error was telling you exactly what was wrong the whole time. You just could not see it yet.