Troubleshooting
WordPress Theme Preview Not Working: Causes and How to Fix It

Short answer
A theme preview usually fails because of a plugin or JavaScript conflict, a security header that blocks the preview frame, mismatched HTTP and HTTPS site URLs, caching or script optimization, or a blocked REST API for block themes. Check the browser console first, then test with plugins disabled.
Key takeaways
- Classic themes preview in the Customizer; block themes preview in the Site Editor.
- Check the browser console first for script errors that name a plugin.
- An X-Frame-Options DENY header can blank the Customizer preview; use SAMEORIGIN.
- WordPress Address and Site Address should match and both use HTTPS.
- Pause JavaScript optimization and CDN script features while testing.
- Block theme previews need a working REST API and a current WordPress version.
Why is my WordPress theme preview not working?
Theme previews usually fail because of a plugin or JavaScript conflict, a security header that blocks the preview frame, mismatched HTTP and HTTPS site URLs, or aggressive caching and script optimization.
When you hover over a theme in Appearance > Themes and click Live Preview, WordPress loads your site with that theme without activating it. Classic themes open in the Customizer. Block themes open in the Site Editor in preview mode.
When this breaks, you might see a blank white preview, an endless loading spinner, a Non-existent changeset UUID style error, or a preview that redirects you back to the Themes screen.
This guide covers the causes in the order that fixes the most cases first. Work on a staging copy if you can, especially before deactivating plugins on a busy site.
What does a broken theme preview look like?
Common symptoms are a blank or grey preview pane, a spinner that never stops, a missing Live Preview button, or an error message instead of your site.
Matching the symptom to a cause saves time:
| Symptom | Likely cause | Where to look first |
|---|---|---|
| Blank preview pane in the Customizer | Security header or mixed HTTP/HTTPS | Site URLs and X-Frame-Options |
| Spinner never stops | JavaScript error or plugin conflict | Browser console and plugins |
| Live Preview button missing | Old WordPress version or theme issue | Dashboard > Updates |
| Preview shows old design | Cache or optimization plugin | Clear caches, pause optimization |
| Error that the theme is broken | Missing files or style.css | Reinstall the theme |
| Site Editor preview fails to load | REST API blocked | Tools > Site Health |
Keep your browser's developer tools open while you test. The console tab often names the exact script or request that fails.
Is a plugin or JavaScript error breaking the preview?
The preview runs on JavaScript in the admin area, so a plugin that loads broken scripts, or one that conflicts with the Customizer or Site Editor, can stop it from loading.
Open your browser's developer tools, switch to the Console tab and reload the preview. Red errors that mention a plugin folder point straight to the culprit.
If nothing obvious shows, run a conflict test:
- Deactivate all plugins, or use a troubleshooting mode tool so only you see the change.
- Try the theme preview again.
- If it works, reactivate plugins one at a time, testing the preview after each one.
- When the preview breaks again, the last plugin you activated is the cause.
Our guide on fixing plugin conflicts explains how to do this without affecting visitors. Common suspects include security, caching, optimization and admin customization plugins.
Is a security header blocking the preview frame?
The Customizer shows the preview inside an iframe, so an X-Frame-Options: DENY header or a strict frame-ancestors rule can make the preview pane blank.
Security plugins, hosting panels and server configs often add headers that stop your site from being shown inside frames. That protects against clickjacking, but DENY also blocks your own Customizer.
The safe setting is SAMEORIGIN, which lets your own site frame itself. MDN's page on the X-Frame-Options header explains the values.
Where to check:
- Security plugins. Look for options named security headers, clickjacking protection or frame options.
- The .htaccess file or server config. Search for X-Frame-Options or Content-Security-Policy.
- Your host or CDN. Some hosts add headers at the server level. Ask support if you cannot find the source.
Change DENY to SAMEORIGIN, or make sure any Content-Security-Policy frame-ancestors rule includes 'self'. Then clear caches and test again.
Do your site URLs match, including HTTPS?
If WordPress Address and Site Address differ, or one uses http and the other https, the browser can block the preview as a cross-origin or mixed-content request.
Go to Settings > General and compare WordPress Address (URL) and Site Address (URL). They should usually be identical and both start with https:// once you have SSL.
Also check how you are logged in. If you open the admin at www.example.com but the site URL is example.com, the preview may count as a different origin.
If you recently moved to HTTPS, read the HTTPS documentation and our guide on installing an SSL certificate on WordPress. Mixed content warnings in the console are a strong clue.
Is caching or script optimization interfering?
Page caching, JavaScript minification, delayed scripts and CDN features such as Rocket Loader can break the preview or show an outdated design.
Caching plugins should skip logged-in users and admin pages, but optimization features sometimes reach the preview anyway. Try these steps:
- Clear every cache. Plugin, host, CDN and browser. Our guide on how to clear cache in WordPress lists each layer.
- Pause JavaScript optimization. Turn off minify, combine and delay JavaScript options for a moment, then test.
- Check CDN script features. Cloudflare's Rocket Loader changes how scripts load and can break admin tools. Turn it off or exclude the admin area.
If the preview works with optimization paused, add exclusions rather than leaving the features off forever.
Is the REST API blocked for block theme previews?
Block theme previews run in the Site Editor, which relies on the REST API, so a security plugin or server rule that blocks REST requests will stop the preview from loading.
Go to Tools > Site Health and look for a REST API error. If one shows, our guide on fixing the REST API error in Site Health walks through the usual causes.
Common blockers are security plugins with disable REST API options, firewall rules on the host, and login or membership plugins that limit API access. Allow REST access for logged-in administrators at minimum.
Also make sure you are on a current WordPress version. Previewing block themes in the Site Editor was added in recent releases, so an outdated install may not show the Live Preview option for block themes at all.
Is the theme itself broken or incomplete?
A theme with missing files, a bad zip upload or a fatal PHP error cannot render a preview, and WordPress may list it as broken.
Check the bottom of Appearance > Themes for a Broken Themes section. A missing style.css is a common cause, covered in our guide on the stylesheet is missing error.
If the theme is listed normally but the preview shows a critical error, delete and reinstall a fresh copy. Some premium themes also need a companion plugin to display properly, so read the theme's setup notes.
To see the underlying PHP error, turn on logging. Our guide on how to enable debug mode in WordPress shows the wp-config.php lines to add.
Could your browser or server limits be the problem?
Ad blockers, privacy extensions and low PHP memory limits can stop the preview, so test in a private window and check Site Health for memory warnings.
Browser extensions sometimes block scripts with names that look like tracking. Open a private window with extensions disabled, log in, and try again.
On the server side, the Customizer loads a lot at once. A low memory limit can produce a blank preview or a 500 error. Site Health shows the current PHP memory limit, and your host can raise it.
Firewall rules such as ModSecurity can also block the long requests the Customizer sends. If your server error log shows blocked requests during preview, ask your host to whitelist them.
Can you switch themes safely without the preview?
Yes; use a staging site, the theme's demo, or a maintenance mode plugin while you test, rather than activating an untested theme on a live site.
If you cannot fix the preview quickly, there are safe ways to evaluate the theme:
- Staging site. Many hosts offer one-click staging. Activate the new theme there and check every page type.
- Theme demo. Look at the theme's demo and its page on the WordPress theme directory.
- Maintenance mode. As a last resort, switch on the live site while a maintenance page is shown, then switch back if needed.
Our guide on how to change a WordPress theme has a checklist for menus, widgets and settings that may change.
What if the post preview is the problem instead?
The Preview button in the post editor is a different feature with different causes, such as caching and domain mismatches, so it needs separate fixes.
If you meant the button that shows a draft post before publishing, read our guide on why preview mode does not work in WordPress. Some causes overlap, such as site URL mismatches and caching, but the steps differ.
If your theme preview works but the theme does not behave after activation, see WordPress theme not working for post-activation fixes.
Frequently asked questions
Why is the Customizer preview blank in WordPress?
A blank preview pane is often caused by a security header that blocks framing, mismatched HTTP and HTTPS URLs, or a JavaScript error. Check Settings > General for matching URLs, look for X-Frame-Options DENY in your security settings, and review the browser console for errors.
Why is there no Live Preview button for my block theme?
Previewing block themes in the Site Editor needs a recent WordPress version. Update WordPress core first. If the button is still missing, the theme may be broken or a plugin may be changing the Themes screen, so test with plugins temporarily disabled.
Can a caching plugin stop theme previews from working?
Yes. Optimization features such as JavaScript minification, combining files and delayed scripts can break admin tools, and stale caches can show an old design. Clear every cache layer and pause optimization while testing, then add exclusions for the admin area.
Is it safe to activate a theme without previewing it?
It is risky on a live site because menus, widgets and layouts can change instantly. Use a staging copy if your host offers one, or enable a maintenance page while you check the new theme, and keep a backup so you can switch back quickly.
Does the theme preview change my live site?
No. Live Preview loads the theme only for you while you look around. Visitors keep seeing the active theme until you click Activate and Publish in the Customizer or activate the theme from the Site Editor preview.
Sources
- Customizer WordPress.org
- HTTPS WordPress Developer Resources
- X-Frame-Options MDN Web Docs
- Rocket Loader Cloudflare Docs
- WordPress theme directory WordPress.org
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.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


