It paginates wrong
The header and footer do not appear
You passed header and footer templates, the option is on, and the pages come out without them. Or they appear as an almost invisible sliver of text at the very top.
What is actually happening
Header and footer templates are rendered in their own context with none of the document's CSS, and with a default font size of zero in some engines. Whatever styling they need has to be inline on the elements themselves. The second cause is page margins too small to contain them: the header is drawn inside the top margin, so a 5mm margin leaves nowhere for it.
Confirming it is this and not something that looks like it
Set an inline background colour on the header template's root element. If a coloured band appears, the template is rendering and the text is the problem. If nothing appears, the margin is.
The fix
Style header and footer templates entirely with inline styles, set an explicit font-size in points, and give the page a top and bottom margin large enough to hold them, typically 15mm or more.
{
"options": {
"format": "A4",
"displayHeaderFooter": true,
"margin": { "top": "20mm", "bottom": "18mm", "left": "16mm", "right": "16mm" },
"headerTemplate": "<div style=\"font-size:9pt;font-family:sans-serif;width:100%;padding:0 16mm;color:#555\">Invoice INV-2481</div>",
"footerTemplate": "<div style=\"font-size:9pt;font-family:sans-serif;width:100%;padding:0 16mm;color:#555;text-align:right\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>"
}
}If that was not it
These produce the same symptom often enough to be worth ruling out before assuming the fix above did not work.
- No font-size in the inline style, which some engines treat as zero rather than as a default
- A margin smaller than the header's own height, which clips it entirely
- Padding on the template needed to line it up with the body's margins, which are separate
- External images in the header, which are subject to the same URL rules as the body
Frequently asked
Does this happen with every rendering engine?
The behaviour behind it is not specific to one tool. Header and footer templates are rendered in their own context with none of the document's CSS, and with a default font size of zero in some engines. Anything rendering HTML to a paged medium has to make the same decision, so the fix travels with you if you change how the render happens.
Will this show up as an error in my logs?
No, and that is what makes it expensive. A document that renders wrong is still a successful render as far as every log line is concerned. It is found by someone opening the file, which is usually the customer.
Related failures
Problems people arrive at from the same starting point, or mistake for this one.
Page breaks land in the wrong place
Nothing told the layout where it is allowed to break, so it breaks wherever the content runs out of page.
Table headers do not repeat on the next page
Header repetition is driven by table sectioning, not by styling.
There is an extra blank page at the end
Something extends a fraction of a millimetre past the end of the last page.
Content is cut off at the right edge of the page
The element is wider than the page's content box and has nothing telling it to wrap.
Page numbers are missing or all show 1
Page numbers come from the footer template's special classes, not from CSS counters in the document body.
CSS for paged documents, and what actually works
Which parts of the paged media specification a browser-based render implements.
Everything that goes wrong, by category
The full list, grouped by where in the pipeline it breaks.
Paste your markup and see the rendered document, without signing up.