The document is wrong
The PDF comes out in dark mode
A document nobody asked to be dark arrives with a near-black background and pale text, usually wasting a great deal of ink and looking wrong next to every other document the recipient has.
What is actually happening
prefers-color-scheme resolved to dark in the render environment, and your stylesheet has a dark block. Headless environments do not have a user preference, so what they report is a default rather than a choice, and it is not always the light one.
Confirming it is this and not something that looks like it
Search your CSS for prefers-color-scheme. If there is a dark block that sets a background on body or a root token, that is it.
The fix
Force the light palette for the document explicitly rather than relying on the environment to report a preference. A document is printed or filed; it has no viewer preference to respect.
/* Documents opt out of the preference entirely. */
:root {
color-scheme: light;
}
@media print {
:root {
--surface: #ffffff;
--text: #111111;
}
}
/* If the document template shares tokens with the app, override at the root of
the document rather than editing the shared dark block. */
.document {
background: #ffffff;
color: #111111;
}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 CSS framework's dark class applied on html by a script that runs before the snapshot
- Tokens defined only inside the dark block, so the light path has no value at all
- An inverted logo asset chosen by the same media query
Frequently asked
Does this happen with every rendering engine?
The behaviour behind it is not specific to one tool. prefers-color-scheme resolved to dark in the render environment, and your stylesheet has a dark block. 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.
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.
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..
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.
Content rendered by JavaScript is missing from the PDF
The snapshot was taken before the script finished.
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.