WordPress Theme PHP Errors: From the Recovery Email to a Clean Log

A critical error screen, a warning banner, or nothing at all

PHP is the language WordPress and every classic theme are written in. It runs on the server before the page reaches the browser, so when it fails, the visitor gets whatever the server could produce instead. That ranges from a full stop to a cosmetic smudge, and the severity tells you how urgent the fix is.

Warnings and notices should never be visible to visitors. If they are, the server is set to display errors, which is a configuration problem on top of a code problem. A white screen with no message is covered in detail in our white screen of death guide, and a generic server failure in the 500 error guide.

What recovery mode does, and what it does not

Since WordPress 5.2, a fatal error caused by a plugin or theme triggers fatal error protection. Visitors see the critical error screen. WordPress sends an email to the site's admin address, or to the address set in a RECOVERY_MODE_EMAIL constant if one is defined, with details of the error and a link to log in using recovery mode. By default it sends that email at most once a day, and the link expires on the same schedule, so check the spam folder before you wait for another.

Logging in through the link pauses the extension that caused the error, but only for your session. WordPress's own developer notes are explicit that pausing does not have global implications: visitors keep seeing the error until the code is fixed or the extension is deactivated. Recovery mode is a way into the dashboard, not a repair. A button in the admin bar exits it and lets everything run again.

Turning on WP_DEBUG_LOG without exposing it

When the email is vague or missing, the debug log gives you the full story. WordPress's debugging documentation describes three constants that go in wp-config.php, above the line that reads 'That's all, stop editing'. WP_DEBUG switches debug mode on. WP_DEBUG_LOG saves every error to a file, by default wp-content/debug.log, or to a path you choose. WP_DEBUG_DISPLAY set to false keeps the messages out of the page HTML.

The same documentation says debugging tools are not recommended on live sites; they belong on local and staging installs. There is a practical reason too. A debug.log in wp-content can often be fetched by anyone who guesses the address, and it may reveal file paths and plugin names. If you must log on production for a few minutes, point WP_DEBUG_LOG at a path outside the public web folder, reproduce the fault, then switch it off. Your host's PHP error log, usually in the control panel, is the other place to look and needs no code at all.

Read each line for the path. An entry that names wp-content/themes/your-theme/ is the theme. One that names wp-content/plugins/ is a plugin, even if the theme took the blame.

Four causes, in the order we find them

1. An old theme meeting a newer PHP

Each major PHP release removes functions that earlier versions only warned about. PHP 8.0 removed create_function() and each(), so a theme that still calls them stops with a fatal error the day the host upgrades. Later 8.x releases added deprecations, such as dynamic class properties in 8.2, that fill logs long before they break anything. Theme requirements have moved accordingly: Newspaper 12.6 needed PHP 8.0 or later, and some users who could not upgrade rolled back to 12.5.1. Check by comparing the PHP version in Tools, Site Health, Info with the theme's stated requirement. The PHP update guide covers the rollback and upgrade order.

2. A theme or companion plugin update

Updates fail in specific, reported ways. After Astra 4.13, one user hit a fatal 'Class "Astra_Notices" not found' from the Astra Pro add-on. A Blocksy 2.1.50 database migration called an undefined function on sites without WooCommerce. Hello Biz 1.2.0 produced a critical error that rolling back fixed. Check the error's file path against your update history; see Blocksy update broke the site and Astra layout broken after an update.

3. A WordPress release changing the rules

WordPress 6.7 began flagging translations loaded too early. Genesis 3.6.0 fixed its own notices, but child themes that keep translated labels in config/layouts.php must move them to config/layouts-labels.php. Hestia's free theme logged errors about missing add-on class files until version 3.3.7 fixed it. These are noise rather than outages, but noise hides real errors. See Genesis PHP errors.

4. A mistake in the child theme's functions.php

This is the cause owners create themselves, usually by pasting a snippet. It gets its own section below.

Child theme functions.php: the file that runs first

WordPress's theme handbook explains that a child theme's functions.php does not replace the parent's. Both load, and the child loads immediately before the parent. That single fact explains most child theme fatals.

• Copying a function from the parent. Declaring a function the parent also declares produces a 'Cannot redeclare' fatal error. The handbook warns against copying parent code for exactly this reason. Use the parent's hooks or filters instead.
• Calling a parent function too early. Because the child file runs first, a parent function called at the top level of the file does not exist yet. Wrap the call in a hook such as after_setup_theme.
• A second opening tag or a missing semicolon. Pasting a snippet that starts with its own opening PHP tag, or drops a semicolon, causes a parse error that takes the whole site down.
• Whitespace after a closing tag. A blank line after a closing PHP tag sends output early and causes 'headers already sent' warnings. Leave the closing tag off the end of the file.

Edit functions.php over SFTP or your host's file manager, not the dashboard's theme editor, so you can undo a mistake when the dashboard is unreachable. Builder sites have their own variant: WPBakery PHP 8 errors and the Bridge white screen after an update both start in bundled code.

Getting from the error message to a working site

1. 1

   Get in

   Use the recovery mode link, or rename the theme's or plugin's folder over SFTP to force WordPress to deactivate it. Take a full backup before changing anything else.

2. 2

   Read the path

   From the email, the host's PHP error log or debug.log on staging, note the file, the line and the PHP version. The path names the culprit.

3. 3

   Check versions

   Compare the theme's required PHP and WordPress versions with yours, and check whether its companion plugins are on matching versions.

4. 4

   Update or roll back

   If the theme is outdated, update it and its companions together. If the latest update caused the error, restore the previous version from backup and report the error to the vendor.

5. 5

   Correct custom code

   If the path points to your child theme, undo the last edit, then reapply it correctly inside a hook.

6. 6

   Confirm a clean log

   Reload the affected pages, then check the log is free of new fatals and warnings. Turn debug logging off again.

Memory errors look similar but are a server limit, not a code fault: see memory exhausted errors.

Staying ahead of the next PHP upgrade

Hosts raise PHP versions on their own schedule, because old versions stop receiving security fixes. The sites that survive are the ones that tested first. Clone the site to staging, switch the staging copy to the new PHP version, browse every template with WP_DEBUG_LOG on, and fix what appears before the host makes the change for you. Keep an eye on themes with slow update histories; a framework that ships a few updates in three years will meet a PHP release it was not written for.

Our theme repair service handles fatals that need code changes, and the hosting and maintenance plans include tested updates and off-server backups so a rollback is always available. The wider WordPress repair library covers individual themes and builders.

Server-side code with too many authors

Every theme, add-on and plugin on a WordPress site runs PHP on the same server, in the same request, written by people who never tested together. The host upgrades PHP for everyone at once. Some of that code will always be behind. A recurring stream of fatals after updates is a symptom of the model, not of bad luck.

A Next.js site can be prerendered at build time, so many pages are static files served from a CDN with no server-side code running per visit, and dependency upgrades are tested in a build before deploy. It costs more up front and needs a developer for structural changes. Compare the trade-offs in WordPress vs Next.js security, then read about a Next.js rebuild. For other symptoms, return to the troubleshooting hub.