The two failure modes you will see
Activation failure shows up in one of two ways. Either WordPress shows a message like "The theme could not be activated because it triggered a fatal error," which is newer WordPress's built-in fatal error protection catching the issue safely, or you get a completely blank white screen with no message at all, which is the classic White Screen of Death from an older or misconfigured setup.
Both point to the same underlying cause: PHP encountered an error it could not recover from while loading the theme's files, most often functions.php, during activation.
Turning on WP_DEBUG to see the real error
Open wp-config.php and set the debug constants near the top of the file, above the "That's all, stop editing!" line. This makes PHP errors, warnings, and notices print directly on the page instead of being suppressed, giving you a file name and line number for the actual problem.
- Open wp-config.php in your site's root directory.
- Set define('WP_DEBUG', true);
- Set define('WP_DEBUG_LOG', true); to also write errors to wp-content/debug.log.
- Set define('WP_DEBUG_DISPLAY', false); if you want errors logged but not shown publicly on a live site.
- Reload the activation attempt or the site homepage and check the debug.log file for the exact error and line number.
Reading a typical fatal error message
A common one looks like: "Fatal error: Uncaught Error: Call to undefined function some_function() in /wp-content/themes/your-theme/functions.php on line 42." This tells you exactly which file and line to open. Common undefined function errors come from calling a function defined in a plugin that is not active, or copying code from a tutorial that assumed a different theme framework was present.
Another frequent one is a parse error, "syntax error, unexpected '}' in functions.php on line X," which means there is a mismatched brace or missing semicolon somewhere before that line; these are pure syntax mistakes rather than logic errors and are usually fast to fix once you see the line number.
Checking PHP version compatibility
If the theme was written using PHP 8 syntax such as named arguments, match expressions, or the nullsafe operator, but the server runs PHP 7.4 or older, activation fails with a parse error even though the code is technically correct for a newer PHP version. Check your hosting control panel or run php -v via SSH to see the active version, and compare it against what the theme code actually requires.
Most hosts let you switch the PHP version per site from a control panel. If you cannot modify the theme code, switching the site to PHP 8.0 or newer resolves this class of error quickly, as long as no plugins depend on the older version.
Missing index.php and other required files
If index.php was accidentally left out of the theme package, WordPress may still allow activation but then show a blank front end, or in some configurations fail activation outright with a missing template error. Confirm index.php exists in the theme's root folder alongside style.css; it is the one template file every WordPress theme is expected to have as a fallback.
Rolling back safely while you debug
If the failed activation leaves the site inaccessible on the front end, you can switch the active theme back via FTP/SFTP by renaming the broken theme's folder in wp-content/themes/; WordPress automatically falls back to a default theme like Twenty Twenty-Four when the active theme's folder is missing or renamed, restoring the site while you fix the code offline.
Test the fix on a local copy of the site or a staging environment before reactivating on production, since repeatedly triggering fatal errors on a live site risks partial page loads being cached by CDNs or visible to real visitors mid-fix.
Frequently asked questions
- How do I see the actual error instead of a blank white screen?
- Enable WP_DEBUG and WP_DEBUG_LOG in wp-config.php; this writes the exact file, line number, and error message to wp-content/debug.log instead of showing a blank page.
- What does "Call to undefined function" usually mean in a theme's functions.php?
- It usually means the code calls a function from a plugin that is not installed or active, or the code was copied from a different theme framework that provided that helper function.
- Can a wrong PHP version really prevent theme activation?
- Yes, if the theme uses syntax from a newer PHP version than the server runs, WordPress will show a parse error and block activation until the code is fixed or the PHP version is upgraded.
- How do I recover if my site goes blank after activating a broken theme?
- Rename the theme's folder via FTP/SFTP; WordPress detects the active theme is missing and automatically falls back to a default installed theme, restoring the front end.