It paginates wrong
The PDF comes out the wrong paper size
You asked for A4 and got Letter, or you set a size in the CSS and the file is something else entirely. The symptom is usually noticed when someone prints it and gets a margin they did not expect.
What is actually happening
Two things can set the page size and they disagree. The render option sets it, and an @page rule in your CSS also sets it, and which one wins depends on the engine. If neither is set, the default is usually Letter, which is why teams outside North America see Letter without ever asking for it.
Confirming it is this and not something that looks like it
Open the file's document properties in any PDF viewer and read the page dimensions. A4 is 210 by 297 millimetres; Letter is 216 by 279.
The fix
Set it in one place. Setting it in the render options is the more predictable of the two because it does not depend on your CSS being parsed the way you expect, but the important part is not setting it in both.
/* If you set it here, do not also set format in the render options. */
@page {
size: A4 portrait;
margin: 18mm 16mm;
}
/* Landscape for one section, if the engine supports named pages. */
@page landscape {
size: A4 landscape;
}
.wide-table {
page: landscape;
}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.
- format and an @page size both set, disagreeing
- A size in pixels, which converts at 96 per inch and rarely lands on a paper size exactly
- landscape set as a render option while the CSS says portrait
- Custom sizes for labels or receipt rolls, which need explicit width and height rather than a name
Frequently asked
Does this happen with every rendering engine?
The behaviour behind it is not specific to one tool. Two things can set the page size and they disagree. 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.
Page margins are ignored in a generated PDF
Same collision as page size: a margin set in the render options and a margin set in an @page rule, with the engine picking one.
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.
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.