Troubleshooting

Troubleshooting

Start with the smallest failing section. Keep the submitted file, stored raw content, plugin versions and the exact error. Repeatedly regenerating an entire page makes the cause harder to find.

Common symptoms

Symptom	Check	Fix direction
Skill not discovered	Installed path, folder structure and client configuration	Keep the complete folder; explicitly request the skill file to test loading
Converter cannot find references	Missing sibling layout skill or incomplete archive extraction	Install the four folders together or use the complete standalone converter archive
Code appears as visible text	Markup pasted into a Paragraph/Custom HTML block	Use the page's Code editor
Unrecognized block	V1 name or required plugin/Pro feature missing	Check installed block types and use the native V2 name
Attempt Recovery	Saved HTML differs from native serialization	Compare native save output and the raw stored content
Icon-bearing Text/Headline becomes invalid	Missing inner span.gb-text, conflicting outer gb-text, or changed icon order	Preserve native sibling icon/label wrappers; see Icon support
CSS changes disappear after editing	Rule exists in css but not styles	Repair the editable source and compile matching CSS
Styles exist but do not apply	Wrong generated selector or theme specificity	Match the actual block class and inspect computed properties
Dark/parent state does not work	Incorrect ancestor selector compilation	Inspect generated CSS; use the tested leading &:is(...) form where applicable
FAQs have no breathing room	Question or answer padding missing/overridden	Set both, then inspect open/closed states and mobile computed padding
Text or decorative content vanishes	Rich-text objects deep-cloned, empty formatting tags discarded	Preserve native rich-text values and use appropriate native elements/Shape
API readback changes {} to []	Explicit empty styles or htmlAttributes	Omit unused attributes instead of serializing empty objects
Links fail after save	Generated action built as Text a or Element a has raw text	Use an Element link with native child blocks
Dynamic tags render literally/empty	Wrong tag syntax, context or missing data	Check the exact catalog and actual records
Style import does not rebrand the site	Existing names were preserved	Review missing-only import behavior and authorize intended shared edits explicitly

Run the local check

python3 skills/generateblocks-layouts/scripts/preflight.py \
  output/layout.html --id-scope YOUR_LAYOUT_SCOPE

A nonzero exit means a detected failure. The tool catches common escaping, object-shape, duplicate-ID, CSS ownership and style-structure errors. It does not fully parse every Pro schema or execute the page.

The native block count may exceed the preflight count: the preflight report focuses on matched attributed free blocks, while the native parser counts recursively across the entire document.

Recovery is not the same as formatting drift

Attribute order and canonical escaping matter when generating output, but an order difference alone is not proof that a saved block is invalid. Check semantic content, native validation and raw-content changes together.

Likewise, zero invalid blocks does not prove the expected text or CSS is present. The About test exposed both valid-but-empty rich text and valid blocks whose CSS targeted the wrong block type.

Cache and editor limits

The tested free 2.5 beta emits local CSS inline. Older free versions support different delivery modes; Pro Global Styles have a separate path. Check the installed version, stored css, current HTML and page cache before using a regeneration procedure from an older guide.

If the editor canvas cannot be inspected, report that limitation. Frontend success and block-parser success should not be described as a completed visual editor check.

For diagnosis by failure, use recovery rules, troubleshooting details and CSS delivery. For a report, include versions, the smallest reproducible markup, expected/actual behavior and redacted errors. Keep credentials and private content out of public issues.

---

Back to wiki home · Reference library