The document is wrong
The generated PDF is blank
You get a valid PDF file of a plausible size, it opens without complaint, and every page is empty. Sometimes it is one blank page, sometimes it is the right number of blank pages, which is the more useful case because it tells you the layout ran.
What is actually happening
Almost always one of three things: the content is rendered by JavaScript that had not run when the snapshot was taken, the body has no height because everything inside it is absolutely positioned or floated, or the markup you sent was empty because the template call returned before the data arrived.
Confirming it is this and not something that looks like it
Count the pages. The right number of blank pages means your layout ran and the content is invisible rather than absent, which points at colour, opacity or a print stylesheet. One blank page means nothing was there at all, which points at the markup or at timing.
The fix
First, log the length of the HTML string immediately before you send it. That single line settles which half of the problem you are in, and it is the step most people skip. If the string is full, render it to a file and open it in a browser: whatever you see there is what the renderer saw.
const html = await renderTemplate(data);
// The one line that halves the search space. An empty or 40-character string
// here means the problem is in your template, not in the render.
console.log("html length:", html.length);
if (html.length < 200) {
throw new Error("template produced nothing; not sending an empty render");
}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.
- A body or wrapper with height: 100vh and overflow: hidden, which clips everything past the first viewport
- Content inside a details element that is closed, or a tab panel with display: none
- opacity: 0 or visibility: hidden applied by an animation library that never ran its reveal
- A single root element with position: fixed, which paints once and leaves the flow empty
Frequently asked
Does this happen with every rendering engine?
The behaviour behind it is not specific to one tool. Almost always one of three things: the content is rendered by JavaScript that had not run when the snapshot was taken, the body has no height because everything inside it is absolutely positioned or floated, or the markup you sent was empty because the template call returned before the data arrived.. 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.
Charts and canvas elements are blank in the PDF
A canvas element draws imperatively.
The generated PDF is far too large
Almost always images at their source resolution.
Background colours and images are missing from the PDF
Browsers drop backgrounds when printing, because a page with every background painted would empty a toner cartridge, and most render APIs inherit that default.
Images do not appear in the PDF
The image src is a path rather than a URL.
The PDF ignores my CSS
The stylesheet is linked rather than embedded, and the link points somewhere the renderer cannot reach: a bundler-generated path, a digested asset filename, or a URL behind your application's authentication.
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.