What Goes Wrong

Most mistakes announce themselves. These do not, which is why they get their own page.

The commented-out tag

Symptom: the body renders in a box you never drew - usually the top-left corner, at a size and width you did not choose. No error anywhere.

Cause: an angle-bracketed foreignObject tag inside an XML comment, above the real one.

<!-- the content block goes here:
     <foreignObject data-slot="content" ...>   <- this one is the problem
-->

The reader that finds your content region takes the first one in the file. It does not know comments from markup, so a commented example is used in place of your real block, and the box lands at defaults.

Fix: never write that tag inside a comment. Spell it as prose - "the long-form content block" - the way the starter template does. The same applies to a commented-out draft of a block you are still working on: delete it rather than commenting it.

This one is worth knowing even if you never comment your files, because it is the first failure most new authors hit and it looks nothing like its cause.

A line height with no unit

Symptom: your file is rejected on submission with a message about line height.

Cause: line-height: 1.65 in the content region's div style.

Fix: write it in pixels - line-height: 30px.

This one is loud on purpose. It used to be silent: an unresolvable ratio quietly became 24px, so a template set correctly in your editor and wrong in every render. Being told at submission is the better failure.

Two content regions

Symptom: the body appears in one box and the other stays empty.

Cause: two data-slot="content" blocks in the file.

Fix: one per template. If you want the body split across two columns, that is not something the markers can express today - tell us what you are trying to do.

A slot the product does not have

Symptom: the slot renders with nothing in it, leaving a gap where you drew text.

Cause: tagging line4 on a template registered for haiku, which has three lines. Or tagging qrCodeSvg on a page template, which has no QR code.

Fix: match the slots to the product type the template is for. Nothing breaks - the slot is simply never filled - but you have drawn something the reader will never see.

Type that only looks right in your editor

Symptom: the template passes review and then real pieces render smaller than you designed.

Cause: you sized the type for the text you typed into the placeholder. The protocol sizes it for the longest text a writer can actually send, and shrinks to fit.

Fix: design the box for the worst case, not the sample. If the shrunk size is too small, the box is too small - see Canvas and readability.

A typeface nobody has

Symptom: everything renders, but in the wrong face.

Cause: naming a font that is not one of the ones the renderer carries. The stack falls through to a default, and a fallback that succeeds looks exactly like a fallback that was intended.

Fix: build your font stack starting with a family the renderer knows, and check the render rather than your editor - your machine has fonts the renderer does not.