How to Fix Breakdance Problems: Builder Not Loading, CSS Not Updating and Templates Not Applying

You open a page in Breakdance and the builder stays blank, spins forever, or loads without your content. Or the builder works, you change a color or a class, and the live site refuses to show it. Or you build a template for blog posts and the posts keep using a different one. None of these leave a dramatic error message, which is why they eat whole afternoons.

Breakdance renders your design from stored element data, generates CSS files from it, and picks a template for each URL using conditions and priorities. Each symptom maps to one of those three systems. This guide shows you how to diagnose each one with Breakdance’s own tools (the Settings, Tools tab and the wp breakdance commands), when the reset buttons are appropriate (almost never), and how Breakdance interacts with caching plugins. Problems shared by all builders after updates are in our general page builder update guide; this one is Breakdance specific.

What is happening

The builder is a browser application that opens at a URL such as /?breakdance=builder&id=POST_ID. It loads the post’s element tree and your global settings, then saves through AJAX requests that carry the parameter _breakdance_doing_ajax=yes. On the front end, Breakdance serves CSS files it generated from your global settings, classes and each post’s elements. It does not rebuild those files on every visit, so stale files are a frequent cause of “my change does not show”.

Symptom	System involved	Most likely causes
Builder blank, spinning or failing to save	Builder app and AJAX	Firewall or security plugin blocking requests (403), PHP errors, plugin script conflicts
Changes saved but the live page looks old	Generated CSS	Stale CSS cache, unwritable upload directories, page cache or CDN
Wrong header, footer or post template	Template resolution	Conditions too broad or too narrow, priority, a disabled template
Imported design looks unstyled	Design Library dependencies	Global settings, classes or presets that the design relies on were not imported

Before you start

You need a WordPress administrator account, plus your hosting control panel or SSH. Before anything else, export your Breakdance settings: go to Breakdance, Settings, Tools and click Download Export File. Breakdance’s documentation says this JSON file holds your global options, settings and preferences, and excludes the license key and some caches. It can still contain sensitive configuration, so store it privately. Also take a normal database backup.

• Server commands run in an SSH terminal from the site folder that contains wp-config.php. WP-CLI is wp on most hosts and wp-cli on some. Breakdance registers its commands under wp breakdance.
• Browser checks use developer tools: F12, or Cmd+Option+I on a Mac.
• Settings changes happen under Breakdance, Settings in wp-admin.

See which Breakdance commands your version offers:

wp help breakdance

This runs over SSH with no placeholders. It lists the subcommands. Breakdance’s documentation describes clear_cache, replace_url, export_settings, import_settings, create_directories, check_directories and license, among others. “Error: ‘breakdance’ is not a registered wp command” means the plugin is inactive or failing to load, which points to a PHP error.

Step 1: Builder will not load or loads blank

Confirm what is failing

Open developer tools, select the Network tab, check Preserve log, then open the builder. Sort by status and look for anything other than 200:

• 403 Forbidden: a firewall, ModSecurity rule, CDN rule or security plugin blocked a builder request. Breakdance’s documentation lists overly aggressive firewalls and security plugins as the usual cause of 403 errors.
• 500: PHP crashed. Check the PHP error log at that minute.
• Pending, then failed: a timeout somewhere between your browser and PHP.
• All 200, but the Console tab shows red errors: a script conflict, often from another plugin injecting JavaScript into the builder page.

Fix 403 blocks

Because every Breakdance AJAX request carries _breakdance_doing_ajax=yes, Breakdance’s documentation suggests asking your host, CDN or security plugin vendor to allow requests with that parameter, rather than switching protection off. In Cloudflare, that means a WAF custom rule with the Skip action for logged-in requests containing that query string. Breakdance also notes that security plugins tend to block saving PHP in a Code Block and uploading SVG files. With Wordfence, put the firewall in learning mode, repeat the blocked action, then switch learning mode off so the rule is allowlisted. Our 403 guide covers firewall false positives in general.

Test for plugin conflicts without breaking the live site

Breakdance has no built-in safe mode, so use the free Health Check and Troubleshooting plugin from WordPress.org. Its Troubleshooting Mode disables plugins and switches theme for your session only. Enable Breakdance alone, test the builder, then add plugins back one at a time. On a staging copy you can bisect faster:

wp plugin list --status=active --field=name
wp plugin deactivate PLUGIN_SLUG_ONE PLUGIN_SLUG_TWO

These run over SSH on staging. The first prints active plugin folder names. PLUGIN_SLUG_ONE and PLUGIN_SLUG_TWO come from that list: deactivate half, test, narrow down. Good output is “Success: Deactivated 2 of 2 plugins.” Leave breakdance active throughout.

Memory and PHP requirements

Breakdance’s server recommendations list PHP 7.4 or higher, the mbstring, curl and zip PHP extensions, a dual-core CPU and 512 MB of RAM, and note that memory needs grow with your other plugins and site size. The separate Breakdance AI add-on requires PHP 8.1 or higher. Check the server side:

php -m | grep -E -i 'mbstring|curl|zip'
wp eval 'echo PHP_VERSION, " / ", ini_get("memory_limit"), PHP_EOL;'

These run over SSH. The first should print curl, mbstring and zip; a missing name means that extension is not loaded for the command-line PHP. The second prints the PHP version and memory limit. The command-line PHP can differ from the web server’s, so confirm under Tools, Site Health, Info, Server. If you see “Allowed memory size exhausted” in the log during builder use, raise memory_limit in your control panel or with define( 'WP_MEMORY_LIMIT', '512M' ); in wp-config.php, as our critical error guide explains.

Step 2: Element or class CSS not updating

This is the most common Breakdance complaint. Work through it in order, checking the live page after each step in a private window.

Regenerate the CSS cache

Go to Breakdance, Settings, Tools and click Regenerate CSS Cache. It rebuilds the generated CSS for the global stylesheet (classes, variables, element defaults) and every post. Breakdance’s documentation says to clear external caches afterward. From the server:

wp breakdance clear_cache

This runs over SSH. Breakdance’s documentation describes it as clearing the Breakdance CSS cache and regenerating it, and suggests it for deployment scripts and changes that do not appear on the front end. Good output ends in a success line. Then purge your caching plugin, server cache and CDN. Hard-refresh the browser (Ctrl+Shift+R, or Cmd+Shift+R on a Mac) because the old CSS file may also be in your browser cache.

Check the upload directories

If regeneration appears to work but nothing changes, Breakdance may be unable to write its files. Breakdance shows a notice when required directories are missing or not writable, and its troubleshooting guide says to run Create Directories on the Tools tab. From the server:

wp breakdance check_directories
wp breakdance create_directories

These run over SSH. The first reports on the upload directories Breakdance writes CSS, fonts and icons into; the second creates any that are missing. Good output shows no missing or unwritable directory. Any path reported as not writable needs its ownership fixed: report the exact path to your host. Ownership problems often appear after a migration where files were copied as root.

Check that the page really uses the CSS you changed

In the browser, right-click the element, choose Inspect, and look at the Styles panel. Each rule shows the stylesheet it came from. If your new value appears but is crossed out, a more specific rule wins: perhaps an element-level setting overriding a class, a theme stylesheet (if the WordPress theme is enabled), or an optimization plugin’s combined file. If your new value does not appear at all, the browser received an old file: a caching layer is still serving it, so look at the response headers of the CSS file in the Network tab (age, cf-cache-status, x-cache) to see which layer.

Step 3: Templates not applying

Every Breakdance template, header, footer and popup has a type, display conditions, a priority and an on or off state. When a URL loads, Breakdance finds every active template of that type whose conditions match, and the one with the highest priority wins.

How conditions combine

Breakdance’s documentation explains that conditions inside one group combine with AND (all must pass), and separate groups combine with OR (any group can pass). A template with no conditions applies to everything of its type. Common mistakes:

• Putting two alternatives in one group, so they must both be true at once and never are. Use two groups instead.
• A broad template (all single posts) with a higher priority than the specific one (posts in one category). The broad one wins every time.
• The template is disabled, or saved as a draft rather than published.
• Two templates with the same priority matching the same URL, which makes the result hard to predict. Give the specific one a higher number.

Fallback templates and the theme

By default Breakdance disables the active WordPress theme, so every type of URL needs a template. Where none of yours match, Breakdance uses its fallback default templates. If a page suddenly looks plain and generic, your template’s conditions stopped matching and the fallback took over. Check the template’s conditions against that URL. A Soft Reset reinstalls the fallback templates, which is one of the few legitimate reasons to use it (see Step 5).

Global Blocks

A Global Block is a reusable layout you edit in one place. If an edit does not appear on pages that use it, regenerate the CSS cache and purge caches; the pages’ HTML may be cached with the old block. If a Global Block shows on one page but not another, check whether the second page uses a copy of the block’s elements rather than the Global Block itself.

Step 4: Design Library imports and Replace URL

Imported designs that look wrong

Designs from a Breakdance Design Library often rely on that design set’s global settings, classes, presets and fonts. If you insert a section without its dependencies, it arrives with the right structure and the wrong styling. Import the design set’s global settings and dependencies when Breakdance offers to, but only after exporting your own settings, because importing global settings can overwrite your design system. Import failures that stop partway are usually the 403 and memory problems from Step 1.

Replace URL after a migration

Breakdance stores image and link URLs inside its element data, so after a domain or HTTPS change, old URLs can linger. Use Replace URL on the Tools tab, or:

wp breakdance replace_url https://OLD_DOMAIN https://NEW_DOMAIN

This runs over SSH after a database backup. OLD_DOMAIN and NEW_DOMAIN are the bare origins with no trailing slash, such as https://staging.example.com and https://www.example.com. It is a raw string replacement in the database with no undo, so a sloppy value (for example just example) can match far more than you intended. Breakdance reports the number of database rows affected; zero means the old URL never appeared in that exact form. Run wp breakdance clear_cache afterward. Other tables still need wp search-replace, as our migration redirect guide explains.

Step 5: The reset buttons, with strong warnings

The Tools tab includes two reset options. Neither one is a troubleshooting step for CSS or builder problems, and neither has an undo.

Tool	What it does	When it is appropriate
Soft Reset	Reinstalls the default icons and fallback templates, removes custom icon sets, and reapplies install defaults including the skip link, the disabled theme setting and Modern Normalize	Fallback templates or icon sets are corrupted, and you have exported settings first
Total Reset	Removes Breakdance’s global options, settings and builder preferences (your design system: global styles, classes, variables, presets) and the license key, then reinstalls defaults. Pages are not deleted.	Almost never on a working site. Only when you deliberately want to start the design system from zero.

Soft Reset can still change your site’s appearance. Reapplying Modern Normalize changes default margins and padding on headings, paragraphs and lists across the site if you had it switched off, and removing custom icon sets breaks every icon that used them.

Total Reset makes every page look broken. Your pages survive, but the global styles and classes they depend on are gone, and the license key must be re-entered. If you or someone else already clicked it, restore your settings from the export file with Import on the Tools tab, or with wp breakdance import_settings FILE.json, where FILE.json is the path to the export file you downloaded. Importing overwrites every option named in the file. With no export file, restore the database from the backup taken before the reset.

Advanced: Breakdance and caching plugins

Most “Breakdance broke after I installed a cache plugin” reports come from three overlapping layers. Configure each deliberately:

1. Page caching. Never cache pages for logged-in users, and exclude any URL containing breakdance=builder. A cached builder page loads stale scripts and data. After a design change, purge the page cache, or visitors keep HTML that references old CSS file versions.
2. JavaScript delay and combining. “Delay JavaScript until interaction” features can stop Breakdance’s front-end scripts for menus, sliders, popups and forms until the first click. If an interactive element only works after you click somewhere, exclude Breakdance’s scripts from delay. Our speed plugin guide shows how to find the script names.
3. CSS optimization. “Remove unused CSS” features build a reduced stylesheet by scanning a page. Classes that only appear after interaction (open menus, popups, hover states, tabs) can be stripped. If those break, exclude Breakdance’s generated CSS files from removal, or turn the feature off and compare.

Prove which layer is guilty with a cache-bypassing request from your own computer:

curl -sI "https://example.com/PAGE_PATH/?nocache=TIMESTAMP" | grep -i -E "cache|age|server"

This runs in a terminal on your computer (macOS and Linux have curl built in; on Windows use WSL, or curl.exe in PowerShell and drop the grep part). example.com/PAGE_PATH/ is the affected page, and TIMESTAMP is any unique value, such as the current time, so the URL is new to every cache. -s hides progress and -I fetches headers only. Headers like cf-cache-status: MISS or x-cache: MISS show the response came fresh from the server. If the fresh response looks right in the browser while the normal URL does not, a cache is serving stale HTML, which our cache layers guide covers in depth.

When to contact your host

Contact your host when the Network tab shows 403 block pages from a server firewall, directories cannot be made writable, or builder requests time out without a PHP error. Send:

• The UTC time of each failure and the builder URL (/?breakdance=builder&id=POST_ID).
• The failing request URL, status code, and response body or firewall reference number, and a note that the requests contain _breakdance_doing_ajax=yes.
• Any path that wp breakdance check_directories reports as not writable.
• PHP error log lines for those minutes, and what changed recently.

If the server is clean and the problem persists in Troubleshooting Mode, contact Breakdance support with the same details. Check headers and status codes from outside your browser with our diagnostic tools, and if the whole site is down, start at the Emergency Room.