How to Fix wkhtmltopdf Version Issues With the First Page and Table of Contents

wkhtmltopdf --version

wkhtmltopdf cover cover.html toc content.html output.pdf

wkhtmltopdf toc result.html result.pdf

wkhtmltopdf cover cover.html toc content.html output.pdf

` with a bold font, or a heading rendered only after JavaScript may not appear in the outline.

Check the source markup

<h1>Installation</h1>
<h2>Linux packages</h2>
<h2>Windows packages</h2>
<h1>Troubleshooting</h1>

Use a consistent hierarchy. A missing `h1` does not always prevent a TOC, but inconsistent nesting makes the resulting outline difficult to interpret. Confirm that the headings exist in the HTML delivered to wkhtmltopdf, not only in a browser-side application state.

Inspect the outline XML

Dump the outline while generating the PDF:

wkhtmltopdf --dump-outline toc.xml toc result.html result.pdf

Open `toc.xml` and check for the expected titles, nesting, links, and page numbers. If the titles are absent, fix the HTML or the page-loading timing before changing TOC styling. If the XML is correct but the printed TOC is blank or misplaced, continue with the default stylesheet test.

Start custom styling from the built-in XSLT

Export the default TOC stylesheet:

wkhtmltopdf --dump-default-toc-xsl > default-toc.xsl

Use that file as the baseline for edits, then pass your copy with the TOC object’s XSL option. A custom XSL stylesheet replaces the default TOC styling options, so remove it during diagnosis. If the default output works, add one XSL change at a time.

4. Fix first-page and page-total symptoms separately

“The first page is missing” can describe three different defects: the cover is not physically in the PDF, the cover is present but has no header or footer, or the TOC has shifted the printed page numbers. Inspect each question independently.

Is the cover physically present?

Open the PDF and count the first page before checking numbering. If it is absent, verify the command contains `cover cover.html` before `toc` and content, and rerun with the patched 0.12.6 binary. A cover object is not included in the TOC, so its absence from the contents list is expected.

Is the TOC object present and populated?

Use `–dump-outline` and inspect the PDF page immediately after the cover. If the XML contains headings but the printed page is blank, remove custom XSL, footer options, and extra CSS, then retest with the default TOC on 0.12.6.

Is the footer total wrong?

Use the smallest possible footer:

wkhtmltopdf --footer-center "Page [page] of [topage]" toc result.html result.pdf

`[page]` is the current page, `[frompage]` is the first page, and `[topage]` is the last page. Compare a run with `toc` to a run without it. A 0.12.5 report produced a 52-page PDF whose footer said “of 57”; removing `toc` made the total correct, while an older 0.12.2.1 build had worked. This comparison identifies a pagination interaction; it does not prove that every wrong total has the same cause.

Do not diagnose totals from a cover alone. Covers intentionally omit headers and footers, so the first visible footer may begin on the TOC or content page.

5. Use this troubleshooting matrix

Symptom	Likely cause	Isolation and fix
Cover is absent	Wrong object order, old release, or unpatched Qt	Run `wkhtmltopdf –version`; install official 0.12.6 with patched Qt; use `cover cover.html toc content.html output.pdf`.
Cover appears but has no footer	Expected cover behavior	Put headers and footers on page objects; do not treat their absence on the cover as a rendering failure.
Printed TOC is blank	No semantic headings, headings unavailable when captured, old 0.12.5 behavior, or broken custom XSL	Run the minimal `toc result.html result.pdf` command, inspect `–dump-outline`, remove custom XSL, and retest on 0.12.6.
TOC appears in the wrong place	Object order or custom XSL/layout rules	Restore cover–TOC–content order and test with the default XSL.
Bookmarks differ from printed TOC	They are separate outputs	Printed contents come from the `toc` object; PDF bookmarks come from `–outline` and heading tags.
`[topage]` is too high	Pagination interaction involving `toc`, version, or footer rendering	Use the minimal footer, compare runs with and without `toc`, and reproduce on patched 0.12.6.
Layout changes after migration	Different libraries, fonts, architecture, or package build	Match the target distribution package, OpenSSL/libc versions, fontconfig/freetype availability, and installed fonts.

6. Make server and container builds reproducible

wkhtmltopdf embeds an old WebKit and depends on native runtime components. The official packaging guidance calls out patched Qt, OpenSSL, libc, fontconfig, and freetype differences between distributions. Fonts are especially important: a missing font changes line wrapping, which changes page breaks and therefore `[topage]`.

After moving to another Linux distribution

1. Record `wkhtmltopdf –version` on both systems, including the patched-Qt text.
2. Confirm the same CPU architecture and a package built for the target distribution.
3. Compare OpenSSL and libc compatibility.
4. Install the same font families and verify fontconfig and freetype can find them.
5. Regenerate the PDF with the minimal cover/TOC command before restoring application options.

Amazon Linux 2 and AWS Lambda

The official FAQ documents a Lambda zip or layer approach. The runtime must expose the bundled libraries and fonts before invoking the binary:

export LD_LIBRARY_PATH=/opt/lib
export FONTCONFIG_PATH=/opt/fonts
/opt/bin/wkhtmltopdf cover cover.html toc content.html output.pdf

Use paths that match your layer. A Lambda package copied from another distribution can fail to start or render different line breaks if its native libraries and fonts do not match the execution environment.

7. Know when wkhtmltopdf is the wrong long-term fix

The project’s maintainer states that Qt 4 has been unsupported since 2015 and the WebKit used by wkhtmltopdf has not been updated since 2012. That maintenance boundary matters when you need modern JavaScript, current CSS, contemporary TLS behavior, or browser features that the embedded engine cannot provide.

For a legacy report that depends on wkhtmltopdf’s established output, standardizing on official 0.12.6 patched-Qt packages and a fixed font/runtime image is the least disruptive remedy. For a new rendering pipeline with modern web requirements, evaluate a maintained browser engine instead of adding more workarounds to an obsolete WebKit.

Or skip the browser setup

If the immediate need is a clean website screenshot rather than a cover-and-TOC PDF, ScreenshotNeo provides a one-request API. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with `X-Page-Verdict` and `X-Billed` headers.

See the ScreenshotNeo API documentation for all options. The following calls are runnable after replacing `YOUR_API_KEY`:

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo also offers an MCP server with `take_screenshot`, `get_page_info`, and `capture_pdf` tools for Claude, Cursor, and other MCP clients. Every feature is included on every plan: 1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account to begin.

FAQ

Does changing only the HTML usually fix a missing TOC?

Not when the executable is an older or unpatched build. Verify the binary and patched-Qt status first, then inspect heading markup.

Can I style the TOC without losing the default behavior?

Yes. Dump the default XSLT, edit that copy, and test it only after the unstyled TOC works.

Should a cover be counted in the printed TOC?

No. A cover object is intentionally excluded; its omission is part of wkhtmltopdf’s document model.

Frequently Asked Questions

Does changing only the HTML usually fix a missing TOC?

Not when the executable is an older or unpatched build. Verify the binary and patched-Qt status first, then inspect heading markup.

Can I style the TOC without losing the default behavior?

Yes. Dump the default XSLT, edit that copy, and test it only after the unstyled TOC works.

Should a cover be counted in the printed TOC?

No. A cover object is intentionally excluded; its omission is part of wkhtmltopdf’s document model.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi