The document is wrong
Background colours and images are missing from the PDF
Your document has coloured headers, tinted table rows or a branded banner on screen, and every one of them comes out white in the PDF. The text is in the right places, so it is clearly your markup, just with the colour drained out of it.
What is actually happening
Browsers drop backgrounds when printing, because a page with every background painted would empty a toner cartridge, and most render APIs inherit that default. This one does not: print_background is on unless you turn it off. So if your backgrounds are missing here and you have not explicitly set it to false, the flag is not your problem and the cause is in the markup or the stylesheet.
Confirming it is this and not something that looks like it
Check the request for an explicit print_background of false, which is the only way to reach the flag-related version of this. If it is absent, open the same HTML in a browser print preview: colours that disappear there are being dropped by your own print stylesheet, and colours that survive point at an element whose background is painted on a parent with no height.
The fix
If something in your code is passing print_background false, remove it: the default is already what you want. Otherwise the flag is a dead end and the answer is below, in the stylesheet. The flag, when it does apply, covers background-color, background-image and gradients on every element at once, so there is no per-element version of it to chase.
{
"html": "<!doctype html>...",
"options": {
"format": "A4",
"printBackground": true
}
}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 print stylesheet that sets background: none, which some CSS resets do deliberately
- print-color-adjust: exact on the element, which forces colour even where the renderer would otherwise economise
- Backgrounds set on a parent that has zero height because its children are floated or absolutely positioned
Frequently asked
Does this happen with every rendering engine?
The behaviour behind it is not specific to one tool. Browsers drop backgrounds when printing, because a page with every background painted would empty a toner cartridge, and most render APIs inherit that default. 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.
SVG images are missing or wrong in the PDF
There are three different problems wearing one symptom.
Images do not appear in the PDF
The image src is a path rather than a URL.
Content rendered by JavaScript is missing from the PDF
The snapshot was taken before the script finished.
The generated PDF is blank
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..
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.