Key facts at a glance
WordPress theme troubleshooting in 2026
Last updated
- The one diagnostic that always helps
- Switch to a default theme like Twenty Twenty-Five. If the problem clears, it was your theme. If not, it is a plugin, PHP, or the server. It never touches your content.
- Your content is safe
- Posts, pages, and media live in the database, not the theme, so switching themes never deletes them. Only the design and theme-specific settings need rebuilding.
- Why old themes break on PHP 8
- PHP 8.0 removed
create_function,each, and curly-brace array access. An older theme using them throws a fatal, not a warning, so the site white-screens. - The broken theme install error
- Stylesheet is missing almost always means you uploaded the whole marketplace bundle. Upload the actual theme zip that sits inside it, the one with
style.cssat its top level. - Customize with a child theme
- Never edit the parent theme, an update overwrites it. A child theme holds your CSS, templates, and functions in a separate folder that survives every parent update.
- Popular themes, same patterns
- Astra, GeneratePress, Kadence, and OceanWP are well coded, so their problems are usually a plugin or builder conflict. Divi and Hello Elementor are builders with their own hubs.
Source: the WordPress theme handbook on child themes, the WordPress documentation on working with themes and the Customizer, the PHP manual on the features removed in PHP 8, and our hands-on theme repairs. Get a quote in 60 seconds →
Why themes break
A WordPress theme is code, and like any code it can hit a fatal error, fall behind the platform it runs on, or collide with another piece of software. That is why theme problems cluster into a few predictable shapes rather than being random. A theme is also the one part of your site you see most directly, so when it breaks the whole site can look broken even when the underlying content is completely intact, which is both reassuring and a useful clue.
The reassuring part is that your content and your theme are separate things. Your posts, pages, and images live in the database and the media library. The theme is just the layer that decides how they look. This is why switching themes never deletes your content, and why activating a default theme is the single most useful troubleshooting step there is: it swaps out the suspect layer without risking anything underneath, and it instantly tells you whether the fault is the theme or something else.
The two problems most specific to themes, and the ones this page treats in depth, are the customization trap and the PHP-compatibility trap. The customization trap is editing the parent theme directly, so a routine update wipes your work, which the child-theme approach exists to prevent. The compatibility trap is an older theme meeting a newer PHP version that removed the functions it relied on, turning a working site into a white screen the moment the host upgrades. Both are common, both are avoidable, and both are quick to fix once you know the pattern.
Where theme problems come from
Almost every theme problem traces to one of these four origins. Naming yours points straight at the fix.
A bad update or a theme switch
The most disruptive origin. A theme update or a switch to a new theme hits a PHP fatal error and the site goes to a white screen or a critical error. The fix is to recover access by activating a default theme or renaming the theme folder, read the debug log for the exact fatal, and then update, roll back, or replace the theme.
Old theme code on a new PHP version
The compatibility trap. An older or abandoned theme uses functions PHP 8 removed, so when the host upgrades PHP the theme throws fatal errors and the site breaks. Revert PHP to get online, then move the theme to a PHP 8 compatible version, patch the removed calls, or migrate to a maintained theme.
An install or activation error
The theme will not install or activate, with a broken theme, missing stylesheet, or missing parent message. Almost always a packaging issue: the wrong zip uploaded from a marketplace bundle, a child theme without its parent, or a Template header that does not match the parent folder. Upload the correct theme zip and install the parent.
Customizing without a child theme
You edited the parent theme directly, and an update overwrote your changes, so your work vanished or the design reverted. This is what child themes prevent. The fix is to set up a child theme, move your CSS, templates, and functions into it, and update the parent safely from then on. Customizer and design issues also live here.
Error and symptom reference
Find the exact message or symptom you see. Each row says what it means and where the fix is.
| Error or symptom | What it means and how to fix it |
|---|---|
| White screen or critical error right after a theme update or switch | A PHP fatal error in the theme code. Switch to a default theme from the dashboard, or rename the theme folder over SFTP to force a fallback, then read the debug log for the exact fatal. |
| "Broken theme: the theme is missing the style.css stylesheet." | You uploaded the whole marketplace download bundle instead of the theme zip inside it, so there is no style.css at the top level. Extract the bundle and upload the actual theme zip. |
| "The parent theme is missing. Please install the parent theme." | A child theme was installed without its parent, or the child style.css Template header does not match the parent folder. Install the parent, and set Template to the exact parent folder slug. |
| The site broke after the host moved to PHP 8.0 or newer | The theme uses code PHP 8 removed, such as create_function, each, or curly-brace array access. Revert PHP to get online, then update, patch, or replace the theme. |
| The Customizer is blank, spins, or will not save | Usually a JavaScript conflict or a low memory limit, not the theme itself. Test with a default theme and plugins disabled, raise memory, and try an incognito window. |
| You edited the theme but the front end does not change | A caching layer is serving an old copy, or a change made in the parent was overwritten by an update. Clear every cache, and move customizations into a child theme. |
| Menus, widgets, or theme options reset after switching themes | Theme-specific settings do not carry between themes. Your content is safe in the database; the design has to be rebuilt in the new theme, or the old theme restored. |
| The design looks broken only on certain pages | Often a page builder or block conflict rather than the theme. Test those pages with the builder disabled, and check the builder repair hubs. |
| The Customize menu item is missing entirely | Your theme is a modern block theme, which uses the full Site Editor instead of the old Customizer. Edit it under Appearance then Editor. |
| The theme update fails, or reverts, or will not apply | A file-permission or memory issue, or a premium theme whose license or bundled updater is not connected. We confirm the update path and apply it cleanly. |
What we fix
Twelve problem areas cover almost every theme emergency. We diagnose which one is actually yours rather than guessing.
Theme Update Broke the Site
A blank page or critical error right after updating the theme. A PHP fatal in the new code. We switch to a safe theme, read the debug log, and move you to a patched version or a maintained theme.
White Screen After Switching Themes
The site goes blank the moment a new theme activates. A fatal in the theme or a memory limit. We recover access and diagnose the exact cause before re-activating.
Broken Theme: Stylesheet Missing
The theme will not install because there is no style.css at the top level, usually the wrong zip from a marketplace bundle. We install the correct theme package.
Parent Theme Missing
A child theme will not activate because its parent is not installed or the Template header is wrong. We install the parent and correct the child so it activates.
Incompatible With PHP 8
An older theme using create_function, each, or curly-brace access throws fatal errors on PHP 8. We revert to get online, then patch or replace the theme.
Customizer Will Not Load or Save
The Customizer is blank, spins, or loses changes. A JavaScript conflict or a low memory limit. We isolate it against a default theme and plugins and fix the cause.
Changes Not Showing on the Front End
Edits do not appear because of caching or because they were made in a parent that an update overwrote. We clear caches and move customizations into a child theme.
Settings Lost After a Theme Change
Menus, widgets, and theme options reset when the theme changed. Your content is safe. We rebuild the design in the new theme or restore the previous one.
Theme vs Plugin or Builder Conflict
The theme fights a plugin or a page builder, breaking a layout or a feature. We isolate the conflict and resolve it without disabling what you need.
Slow or Heavy Theme
A bloated theme drags load times and responsiveness. We measure the cost, trim it, and where the theme itself is the bottleneck, advise a lighter one.
Customizing Safely With a Child Theme
We set up a proper child theme so your CSS, templates, and functions survive every future update of the parent theme.
Abandoned or Nulled Theme
A theme that no longer gets updates, or a pirated copy carrying malware, is a standing risk. We migrate you to a maintained, clean theme with the design preserved.
Problems with specific themes
We work on every popular theme. Most theme problems follow the same patterns whatever you run, but here is how they tend to show up on the themes we see most, and where two of the big names have their own dedicated hubs.
Astra
Among the most-installed themes, over a million active sites. Well coded, so problems are usually a plugin conflict, a Starter Templates import failing on low resources, or an addon license.
GeneratePress
A lightweight, hook-based theme. Issues are typically a child-theme or hook customization, or a conflict with a builder rather than the theme itself.
Kadence
A block-friendly theme with a header and footer builder. Problems tend to be block or builder conflicts and header or global-color settings not applying.
OceanWP
A free theme with many extensions and demo imports. Issues are usually the demo import, an extension conflict, or settings not saving.
Neve and Blocksy
Modern lightweight themes with starter sites and header builders. Problems are usually starter-site import, the Customizer or Site Editor, or a plugin conflict.
Divi
A theme and Visual Builder in one. Its builder-specific failures, loading, saving, and static CSS, have a dedicated hub.
Divi repair hub →Hello Elementor
The near-blank theme built for Elementor, so almost every problem is really an Elementor problem, covered on the Elementor hub.
Elementor repair hub →Block and default themes
Twenty Twenty-Five and other block themes use the full Site Editor under Appearance then Editor, not the old Customizer, which is why the Customize menu can appear to be missing.
Updating and customizing safely
Most theme emergencies are preventable. Three habits stop the great majority of them, and they are the same steps we take before touching any theme.
Before assuming a problem is your theme, switch to a default theme like Twenty Twenty-Five and check whether it persists. If the site works on the default theme, the fault is your theme, and if it does not, the cause is a plugin, PHP, or the server. This one step saves more wasted time than any other, and because your content is untouched it is completely safe to do on a live site for a moment.
Never edit the parent theme directly. Put your CSS, template overrides, and custom functions in a child theme, a small separate theme whose style.css names the parent in a Template header and whose functions.php adds to, rather than replaces, the parent. When the parent updates, your child theme is untouched, so your work survives. Copying parent functions into the child causes duplicate-function fatal errors, so add, do not copy.
Before a host moves you to a new PHP version, confirm your theme supports it, especially if the theme is older or no longer maintained. PHP 8 removed functions like create_function and each that old themes relied on, so an unmaintained theme can white-screen the moment PHP is upgraded. If a theme has not been updated in years, treat a PHP upgrade as the moment to plan a move to a maintained one.
Take a backup, or update on a staging copy first, before a major theme update, so a bad update is a restore rather than an emergency. This matters most for premium themes bundled with a builder or many features, where an update touches a lot at once. If the update breaks something, you roll back instead of firefighting a live site.
Why specialist theme work helps
The tricky part of theme problems is that the theme is the most visible layer, so almost anything wrong with a site looks like a theme problem, when often it is a plugin, a PHP version, or a cache. A lot of do-it-yourself theme troubleshooting is really spent proving what the cause is not, and doing that safely on a live site, without losing customizations or breaking the design further, is exactly the nervous work most owners would rather hand off. The skill is going straight to the fault: recover a white-screened site fast, read the debug log, isolate against a default theme, and know when a symptom is the theme versus a builder or a plugin.
We do this all day, so the process is the same every time. Confirm whether the theme is actually the cause by testing a default theme. If it is a fatal, read the log and get the exact file and line. Then apply the right fix: recover access, roll back or update the theme, patch a PHP incompatibility, install the correct package, set up a child theme so customizations stop getting overwritten, or resolve a conflict with a plugin or builder. We charge a flat rate because we are fast at finding the one cause that matters, rather than billing hours against guesswork.
The 2-hour guarantee and the money-back promise are the enforcement. We do not get paid if we cannot fix the theme problem for the agreed scope. If the real answer is that an abandoned theme has to be replaced, we tell you that up front and preserve the design in a maintained theme rather than patching something that will keep breaking.
Related fixes and hubs
Theme problems often sit next to a broader WordPress issue, or a page builder. These are the pages for the ones that reach past the theme itself.
White screen or critical errorA blank page or a critical error for every visitor. Often a theme fatal, but also plugins, PHP, or memory. The debug log names the cause.
Recover a critical error →Site broke after a PHP 8 upgradeAn old theme or plugin uses code PHP 8 removed and throws a fatal. Revert to get online, then patch or replace the code and move forward.
Fix a PHP version break →Built with Elementor or Hello themeThe Elementor repair hub. If your theme is Hello Elementor, almost every problem is really an Elementor problem.
Elementor repair hub →Running the Divi themeThe Divi repair hub. Divi is a theme and Visual Builder in one, with its own loading, saving, and static-CSS fixes.
Divi repair hub →A heavy theme is slowing the siteBloated themes drag load times and Core Web Vitals. We measure the cost and trim it, or advise a lighter theme where the theme is the bottleneck.
Speed optimization →Everything WordPress repairThe parent hub for plugin, theme, update, and critical-error repairs across WordPress, with themes as one part of it.
Visit the WordPress hub →Pricing and process
Send your site and the symptom
Use the quote form with your URL, your theme, and what happened, a broken update, an install error, or a lost customization. A senior engineer replies with a flat-rate quote, usually within 30 minutes during business hours.
Approve, we start immediately
No scheduling step, no kickoff call. Approve the quote and we begin. You provide WordPress and hosting access through a secure link. The clock starts on the 2-hour guarantee.
Fixed and protected
We fix the real cause, set up a child theme where it prevents a repeat, confirm the design and the site work, and tell you what happened. Money back if we cannot fix it for the agreed scope.
WordPress theme FAQ
A theme update broke my site, or I see a white screen after updating the theme. What do I do?
A blank page or a There has been a critical error message right after a theme update is a PHP fatal error in the new theme code, and the priority is to get back online. The fastest recovery is to switch away from the broken theme. If you can still reach the dashboard, activate a default theme like Twenty Twenty-Five under Appearance then Themes. If the admin is down too, rename the active theme folder over SFTP or in your host file manager, which forces WordPress to fall back to a default theme, or restore the previous theme version from a backup. Once the site is back, enable the debug log to read the exact fatal, which names the file and line, and from there the fix is usually a theme update to a patched version, a rollback, or, if the theme is abandoned, a move to a maintained one.
Why will my theme not activate, with a "Broken theme: the theme is missing the style.css stylesheet" error?
That error means the theme package you uploaded does not have a style.css file at the top level of its folder, and it is almost always caused by uploading the wrong file. When you buy a theme from a marketplace, the download is a bundle that contains documentation, licensing, sometimes a child theme, and the actual theme zip inside it. If you upload that whole bundle, WordPress looks for style.css, does not find it at the top level, and reports the theme as broken. The fix is to extract the bundle, find the actual theme zip inside, usually named for the theme itself, and upload that one. For a theme you built or edited, make sure style.css exists in the theme folder with a valid theme header, because that file is what identifies a folder as a theme.
Why does WordPress say "the parent theme is missing"?
You are installing a child theme without its parent, or the child cannot find the parent it names. A child theme is not a full theme on its own, it only holds your changes and depends on a parent theme for everything else, so the parent has to be installed too. The message usually also names which parent it needs. Install that parent theme first, then activate the child. If the parent is already installed and you still see the error, the Template line in the child theme style.css does not match the parent folder name, which is case-sensitive and must be the exact folder slug, for example twentytwentyfive rather than Twenty Twenty-Five. Correct the Template value to the parent folder name and the child theme activates.
My old theme broke after my host moved me to PHP 8. Why, and how is it fixed?
Older themes often use PHP features that PHP 8 removed, so on the newer version they throw fatal errors instead of running, which takes the site down. The common culprits are create_function and each, both removed in PHP 8.0 after being deprecated in 7.2, and the curly-brace syntax for array access like the old style with braces, removed in PHP 8.0 after being deprecated in 7.4. A theme written years ago and no longer updated can contain any of these, so a host that forces a PHP upgrade turns them into fatal errors. The immediate fix is to revert PHP to the previous version in your hosting panel to get back online, then either update the theme to a version its author made PHP 8 compatible, patch the specific removed calls, or migrate to a maintained theme. We cover the broader version transition on our PHP 8.4 fix page.
How do I customize my theme without losing my changes when it updates?
Use a child theme, which is the WordPress-supported way to customize a theme that still receives updates. The rule is simple: never edit the parent theme directly, because a theme update overwrites its files and your changes are gone. A child theme is a small separate theme, its own folder with a style.css that names the parent in a Template header and a functions.php, and you put your CSS, template overrides, and custom functions there instead. When the parent updates, your child theme folder is untouched, so your work survives. One important detail: a child theme functions.php does not replace the parent one, it loads in addition to it, so you add hooks and functions there rather than copying the parent code, which would cause duplicate-function fatal errors. Set up correctly, a child theme lets you update the parent safely forever.
The Customizer will not load, or my changes will not save. How do I fix it?
A blank or spinning Customizer, or one that will not save, is usually a JavaScript conflict or a server limit rather than a broken theme. Work through the standard isolation. Temporarily switch to a default theme and open the Customizer: if it works, the problem is your theme, and if it does not, the cause is elsewhere. Deactivate your plugins and retest, then reactivate them one at a time to find a conflict. Check that your memory limit is high enough, because the Customizer loads a live preview of the whole site and can exhaust a low limit. Also try a different browser or an incognito window to rule out a browser extension. Note that block themes use the full Site Editor rather than the old Customizer, so if your Customize menu item is missing, your theme is a block theme and you edit it under Appearance then Editor instead.
I edited my theme but the changes are not showing on the front end. Why?
Two common causes. The first is caching: a caching plugin, your host page cache, or a CDN is serving an old copy, so clear each of those and do a hard browser refresh. The second is where you made the change. If you edited the parent theme directly and a child theme is active, or a theme update has since run, your change may have been overridden or overwritten. Custom CSS added in the Customizer or a child theme should apply, but CSS added straight into a parent theme file is lost on update, which is exactly why customizations belong in a child theme. If the change still does not appear after clearing every cache, confirm you edited the file that is actually loading, the active theme or its child, and not a copy elsewhere.
Do you fix problems with specific themes like Astra, GeneratePress, Kadence, OceanWP, or Divi?
Yes. We work on all the popular themes, and most theme problems follow the same patterns regardless of which theme you run, a bad update, a PHP incompatibility, a plugin conflict, a Customizer issue, or a lost customization. Astra, GeneratePress, Kadence, OceanWP, Neve, and Blocksy are all well-coded, lightweight themes, so their problems are more often a conflict with a plugin or a page builder than a fault in the theme itself, which is exactly the kind of thing conflict isolation resolves. Two of the big names are really page builders as much as themes and have their own dedicated hubs: Divi, which we cover on the Divi repair page, and Hello Elementor, the blank theme built for Elementor, which we cover on the Elementor repair page. Whatever theme you run, we diagnose the actual cause rather than guessing.
Is a broken theme the same as the WordPress white screen of death?
They overlap but are not the same. A theme can cause the white screen of death, a blank page or a critical error for every visitor, when its code hits a PHP fatal error, and that is one of the most common triggers. But the white screen can also come from a plugin, a PHP version change, or a memory limit, none of which are theme problems. The way to tell is to switch to a default theme: if the site comes back, the theme was the cause and you are in the right place, and if it stays broken, the problem is elsewhere and our white screen page walks the other causes. This theme page focuses on problems that are specifically the theme, activation, updates, the Customizer, child themes, and theme-specific PHP compatibility.
Should I just switch themes, and will I lose my content if I do?
Your content is safe. Posts, pages, images, and most settings live in the database and the media library, not in the theme, so switching themes does not delete them. What does not carry over is the design and any theme-specific settings: menus may need reassigning to the new theme locations, widgets can move or disappear, and options a theme stored in its own settings, like a header layout or custom colors, belong to that theme and will not appear in a different one. So switching is safe for your content but means rebuilding the look in the new theme. It is also the single best diagnostic step, because temporarily activating a default theme instantly tells you whether a problem is your theme or something else, without risking any of your content.
Sources and further reading
The theme and child-theme guidance comes from the WordPress theme handbook and documentation; the PHP compatibility facts from the PHP manual.