Troubleshooting

Most Bialty troubleshooting comes down to one mistake:

the wrong layer is being inspected.

Start with the frontend, not the Media Library.

First check: are you testing the rendered frontend HTML?

The product acts on rendered output.

So the first diagnostic question is:

• are you looking at a published frontend page or product;
• or are you looking at editor state, raw metadata, or the Media Library?

If you are not on the real frontend output, you are not checking the right thing yet.

Second check: clear cache

If your site uses:

• page cache
• server cache
• CDN cache
• performance plugins

then clear those layers before you judge the result.

Dynamic output can look “unchanged” simply because the old HTML is still being served.

Third check: validate the rule itself

Make sure the configured rule actually has a usable signal.

For example:

• if the rule uses a focus keyword, confirm the post really has one;
• if the rule uses a title, confirm the title is what you expect;
• if the rule uses the image name, confirm the filename is meaningful.

Fourth check: confirm scope

Free and commercial scope are not the same.

If you are testing:

• custom post types;
• WooCommerce;
• store-specific templates;

then confirm that the installed edition matches the scope you are testing.

Fifth check: builders and custom templates

If the site uses a builder, theme framework, or template layer that bypasses the standard frontend pipeline, Bialty may not touch that output in the same way.

Common pattern:

• standard posts work;
• a builder-heavy template behaves differently;
• a custom product widget behaves differently;
• a sidebar or header image never changes.

That usually means the output path is different, not that the plugin is “random”.

When to use debug mode

Debug mode is for advanced troubleshooting.

Use it when you suspect the normal wrapper strategy is creating a conflict with:

• styling;
• DOM structure;
• theme rendering;
• builder output.

Do not present debug mode as the normal operating mode. It exists to isolate edge cases.

WooCommerce-specific checks

For stores, validate all of the following separately:

1. main product image
2. product gallery
3. variable-product behavior if relevant
4. related-product or merchandising sections
5. cache behavior after settings changes

WooCommerce issues are often template issues, not core rule issues.

A practical troubleshooting checklist

1. Publish or open a real frontend page.
2. Purge cache.
3. Confirm the rule and signal source.
4. Confirm the edition and scope.
5. Test without builder edit mode.
6. Test debug mode only if the wrapper seems to be the problem.
7. Isolate the exact template zone that fails.

The most useful mindset

Bialty troubleshooting is easier when you stop asking:

why did the Media Library not change?

and start asking:

what HTML was actually rendered for this frontend request?