Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Troubleshooting

WordPress Theme Not Working: Causes and How to Fix It

WordPress Theme Not Working: Causes and How to Fix It

Short answer

A theme stops working because of a wrong zip upload, a missing parent theme, a PHP error or old PHP version, a plugin conflict, missing demo content, or caching. Match your symptom to the cause, check the debug log, and test with plugins disabled before replacing the theme.

Key takeaways

  • Upload the installable theme zip, not the full download bundle.
  • Child themes need their parent theme installed with the matching folder name.
  • Critical errors after activation usually point to PHP version, memory or code errors in the debug log.
  • Themes only look like their demo after importing demo content and companion plugins.
  • Test plugin conflicts safely with the Health Check troubleshooting mode.

Why is your WordPress theme not working?

A WordPress theme usually stops working because of a bad upload, a missing parent theme, a plugin conflict, an old PHP version, missing required plugins, or a cache showing outdated pages.

Not working can mean many things. The theme might refuse to install, show a critical error when activated, look nothing like the demo, or ignore your changes.

Match your symptom to the likely cause first:

SymptomLikely causeWhere to look
The package could not be installedWrong zip uploadedThe file you downloaded
The parent theme is missingChild theme without its parentAppearance > Themes
Critical error or blank screen after activatingPHP error, memory limit, plugin conflictDebug log, error email
Theme looks nothing like the demoDemo content and plugins not importedTheme setup wizard
Customizer or Site Editor will not loadPlugin conflict or JavaScript errorBrowser console
Changes do not show on the siteCachingCache plugin, CDN, browser

The sections below take each one in turn.

Why won't your theme install?

Theme uploads usually fail because you uploaded the full download package instead of the installable theme zip, or the file is too large for your server's upload limit.

Premium themes often come in a bundle with documentation, licenses and child themes inside. WordPress needs the inner zip that contains the theme's style.css file.

If you see The package could not be installed. The theme is missing the style.css stylesheet, unzip the download on your computer and look for a zip named after the theme. Upload that one instead.

If you see a message about the file exceeding the maximum upload size, ask your host to raise the limit or upload the unzipped folder to wp-content/themes with SFTP. Our guide on installing a WordPress theme from a zip file shows both methods.

Why does WordPress say the parent theme is missing?

You installed a child theme without its parent theme; install the parent theme with the exact folder name the child expects, then activate the child theme again.

A child theme borrows templates and styles from a parent. Its style.css includes a Template line naming the parent's folder. If that folder does not exist, WordPress marks the child as broken.

Fix it in three steps:

  1. Find the parent theme name in the child's style.css or documentation.
  2. Install the parent theme from Appearance > Themes or from its zip.
  3. Activate the child theme, not the parent.

The child themes handbook page explains how the Template line works. Our explainer on what a child theme is covers when you need one.

What if activating the theme causes a critical error?

A critical error after activation means the theme's PHP code failed, usually from an incompatible PHP version, low memory, or a clash with a plugin; check the error email or debug log to find the file.

WordPress often sends an email to the admin address with a recovery mode link. That link lets you log in and switch themes even when the site is down. Our guide on using WordPress recovery mode walks through it.

If you get no email, rename the theme's folder in wp-content/themes with SFTP or your host's file manager. WordPress then falls back to a default theme if one is installed.

To see the actual error, turn on debugging. The Debugging in WordPress guide shows the wp-config settings, and our guide on enabling debug mode explains where the log file appears.

Common errors and fixes:

  • Syntax or fatal errors in theme files often mean the theme needs a newer PHP version or an update.
  • Allowed memory size exhausted means you need to increase the PHP memory limit.
  • Call to undefined function often means a required plugin is missing.

Is your PHP or WordPress version too old for the theme?

Yes, this is common: modern themes declare minimum PHP and WordPress versions, and running older versions can cause errors or missing features.

Check the theme's page in the directory or the seller's documentation for Requires PHP and Requires at least. Then compare with Tools > Site Health > Info.

Older PHP versions also stop receiving security fixes. The PHP supported versions page shows which versions are still maintained.

Our guide on which PHP version to use for WordPress helps you choose a safe target.

Why doesn't your theme look like the demo?

Themes look like their demo only after you import the demo content, install the recommended plugins and set the same pages and menus; activating the theme alone gives a mostly empty layout.

Demo sites are full of sample posts, images, menus, widgets and page builder layouts. None of that comes with the theme files.

Look for a setup wizard or Starter templates option after activation. Many themes also show a notice asking you to install companion plugins, such as a page builder or a blocks plugin.

Also check the home page setting. Go to Settings > Reading and set your home page to a static page if the demo uses one.

Could a plugin be breaking your theme?

Yes, plugin conflicts are one of the most common reasons a theme misbehaves, especially page builders, optimization plugins and plugins that add their own styles.

The quickest test is to deactivate all plugins, check the theme, then reactivate them one at a time until the problem returns.

On a live site, do this safely with the Health Check & Troubleshooting plugin. Its troubleshooting mode disables plugins and switches themes only for your login, so visitors see the normal site.

Our guide on fixing a plugin conflict covers the full process.

Why won't the Customizer or Site Editor load?

When the Customizer or Site Editor shows a blank or spinning screen, a JavaScript error from a plugin or theme script is the usual cause, along with low memory or a security plugin blocking requests.

Open your browser's developer tools and look at the Console tab while the screen loads. Red errors name the script that failed. Chrome's Console overview explains how to read them.

Then try:

  1. Disabling plugins one by one, starting with optimization and security plugins.
  2. Clearing caches and turning off JavaScript minification.
  3. Increasing the PHP memory limit.
  4. Checking whether a firewall blocks admin-ajax.php or REST API requests.

Remember that block themes use the Site Editor, while classic themes use the Customizer. If you are looking for the Customizer on a block theme, it may not appear in the menu at all.

Why are your theme changes not showing?

Theme changes usually do not appear because a caching plugin, server cache, CDN or your browser is serving an older copy of the page or stylesheet.

Clear every cache layer, then test in a private browser window. Our guide on clearing cache in WordPress covers each one.

If you edited theme files directly, an update may have overwritten them. Put custom code in a child theme or Additional CSS instead.

What if a theme update broke your site?

If the problem started right after a theme update, roll back to the previous version or restore a backup, then wait for a fixed release or test the update on staging.

Our dedicated guide on fixing a theme that broke your site after an update covers this case step by step.

If you only need the old version back, see how to revert a WordPress theme update.

When should you switch themes instead?

Switch themes if the theme is abandoned, has not been updated for a long time, does not support your PHP version, or keeps conflicting with essential plugins.

An unmaintained theme is a security risk as well as a source of bugs. Check the Last updated date on its directory page or changelog.

Before switching, back up your site and test the new theme on a staging copy. Our guide on changing a WordPress theme explains what to check so you do not lose widgets, menus or layout settings.

Frequently asked questions

How do I switch themes if I cannot log in to WordPress?

Rename your active theme's folder in wp-content/themes using SFTP or your host's file manager. WordPress will fall back to a default theme if one is installed. If none is installed, upload a default theme folder first, then rename the broken one.

Why does my theme work on one site but not another?

The two sites probably differ in PHP version, memory limits, active plugins or server settings. Compare them in Tools, Site Health, Info. A plugin that exists only on the broken site is the most common difference.

Will switching themes delete my content?

No. Posts, pages, media and users are stored in the database and stay the same. You may lose theme-specific items such as widget placements, menu locations, shortcodes and Customizer settings, so review those after switching.

Why does my premium theme say the license is invalid?

License errors usually mean the license key has expired, is used on too many sites, or the site address changed. Check your account on the seller's website. An invalid license normally blocks updates and support rather than breaking the theme itself.

Should I contact the theme developer?

Yes, after basic checks. Share your WordPress and PHP versions, the exact error message, and whether the problem remains with all plugins disabled. That information helps developers spot bugs quickly and shows you have ruled out common causes.

Sources

  1. Child Themes WordPress Developer Resources
  2. Debugging in WordPress WordPress Developer Resources
  3. Health Check & Troubleshooting WordPress.org Plugin Directory
  4. Supported Versions PHP.net
  5. Console overview Chrome for Developers

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

Written and checked byWPLegible Editorial Team Independent WordPress reviews and guides

Researched from the primary sources listed above and checked against our editorial rules before publishing.