What goes wrong when HTML becomes a 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.

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 image src is a path rather than a URL.

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.

The snapshot was taken before the script finished.

The render viewport is narrower than your first breakpoint, so your own media queries are doing exactly what you told them to.

prefers-color-scheme resolved to dark in the render environment, and your stylesheet has a dark block.

A canvas element draws imperatively.

There are three different problems wearing one symptom.

Almost always images at their source resolution.

Either the markup styles something to look like a link without being an anchor, or the anchor href is relative.

Nothing told the layout where it is allowed to break, so it breaks wherever the content runs out of page.

Header repetition is driven by table sectioning, not by styling.

Something extends a fraction of a millimetre past the end of the last page.

The element is wider than the page's content box and has nothing telling it to wrap.

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.

Page numbers come from the footer template's special classes, not from CSS counters in the document body.

Two things can set the page size and they disagree.

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.

Fixed positioning means fixed to the viewport, and a paged document has one viewport per page or none at all depending on the engine.

Break rules apply to items, not to containers, and a flex or grid container that is taller than a page has to break somewhere.

The orphans and widows properties default to a value of 2 in most engines, which is low enough that a single stranded line is still legal in a lot of cases, particularly with short paragraphs.

The font file was not fetched.

The font in use has no glyphs for those characters, and no font on the render machine does either.

Emoji need a dedicated font, and colour emoji need one in a colour font format.

Two separate problems.

The text is not text.

The font is not the same.

The default wrapping rules break lines at spaces and a handful of punctuation marks.

A headless browser is not a self-contained binary.

This is the previous error with the first missing library named.

The default wait condition is the network going idle, and something on the page is keeping it busy: an analytics beacon, a font request to a host that is not responding, a polling request, or an ad script.

The tab crashed, and by far the most common reason is memory.

A full browser build is several hundred megabytes and the unzipped package limit is 250MB.

Two multiplying factors.

A browser launched per request has to be closed, and the close is skipped whenever the render throws before reaching it.

Docker gives a container 64MB of shared memory by default, and a browser uses shared memory heavily for its renderer processes.

Usually waiting rather than working.

The bytes were treated as text somewhere.

Content-Disposition is absent or set to inline.

The request body exceeded a limit.

The key that arrived is not the key you think you sent.

Unbounded concurrency.

The response was cut off.