If a wkhtmltopdf table header is drawn on top of the first body row after a page break, treat it as a renderer-and-layout interaction rather than a single universal bug. Confirm the exact binary and environment, reduce the document to a minimal table, then test header display, print wrappers, flex/overflow rules, rowspans and page-boundary content in that order. The safest change depends on whether column headings must repeat.
First, identify which outcome you need
When repeated headings are optional
The simplest reported workaround is to stop wkhtmltopdf treating the thead as a repeating table-header group:
thead {
display: table-row-group;
}This can prevent the overlapping repeat, but headings will no longer be printed automatically on subsequent pages. Use it only when the first-page heading is sufficient or you can add equivalent labels another way.
When headings must repeat
Keep the header-group behavior and test the following candidate rules:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problems#1 Best Overall
thead {
display: table-header-group;
break-inside: avoid;
page-break-inside: avoid;
}These declarations are reported issue-thread suggestions, not a guaranteed patch. A separate report describes blank gaps and a repeated header without its following data row even with similar page-break rules, so inspect the resulting PDF rather than assuming success.
Reproduce the failure with a minimal document
Before changing a production template, make a small file that still fails. This distinguishes table pagination from unrelated page elements.
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>
@page { size: A4; margin: 18mm; }
body { font: 10pt Arial, sans-serif; }
table { width: 100%; border-collapse: collapse; }
th, td { border: 1px solid #999; padding: 5px; }
thead { display: table-header-group; }
tr { page-break-inside: avoid; }
</style>
</head>
<body>
<table>
<thead><tr><th>Item</th><th>Description</th></tr></thead>
<tbody>
<!-- repeat enough rows to force several pages -->
<tr><td>1</td><td>A deliberately long description ...</td></tr>
</tbody>
</table>
</body>
</html>Generate it with the exact command and binary used in deployment, for example:
wkhtmltopdf --print-media-type minimal.html minimal.pdf
wkhtmltopdf --versionRecord the operating system, wrapper or library, print-media setting, page number where overlap starts and the complete version string. Reports differ by setup, including a report involving wkhtmltopdf 0.12.4 on Windows 7, so a result from another build is not proof that your production renderer behaves the same.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #2
Check table structure before styling
Use one semantic table with a single header group and a body group:
- Put column headings in
<thead>, data rows in<tbody>, and totals in<tfoot>only when they are genuinely totals. - Do not place a second header row in the body and expect wkhtmltopdf to coordinate it with a repeating
thead. - Check that every row has the expected number of cells. Complex
colspanandrowspancombinations can alter pagination calculations. - Temporarily remove decorative nested tables, absolutely positioned elements and scripts that change row height while the page is loading.
Validate the reduced file first, then add template features one at a time. This gives you a regression case for every subsequent change.
Inspect wrappers and print layout
Responsive overflow containers
Issue commenters report improvement after removing a responsive .table-responsive wrapper or making its print overflow visible. Test a print-only override:
@media print {
.table-responsive {
overflow: visible !important;
display: block !important;
}
}If removing the wrapper fixes the PDF, retain the wrapper for screen CSS and disable only the behavior that interferes with print pagination. Overflow changes can affect clipping and horizontal layout, so check wide tables as well as the header.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Flex containers
A flex parent can change the table’s available height or width during pagination. As a diagnostic, switch the immediate print parent to block:
@media print {
.table-wrapper,
.table-wrapper > * {
display: block !important;
}
}Use the narrowest selector that reproduces the correction. This is an anecdotal workaround, not a rule that every flex layout is defective; it may change alignment, widths or neighboring content.
Look for page-boundary edge cases
Rowspans
Large rowspans can leave wkhtmltopdf deciding that a header fits while the associated body content is laid out differently. Temporarily remove the rowspan or split the logical section into separate tables. One issue commenter reports inserting an empty row after a rowspan section as a workaround for a particular document. Treat that as a last-resort experiment, not a general requirement, and verify that the empty row does not appear visibly or create an unwanted gap.
Unusually tall rows
A row containing long unbreakable text, an image, or generated content may straddle the page boundary. Test with shorter text and fixed image dimensions. If the defect disappears, reduce the row’s minimum height, allow sensible wrapping, or split the content into multiple rows. Keep tr { page-break-inside: avoid; } only when the resulting blank space is acceptable; forcing every tall row to stay intact can itself produce large gaps.
Rank #4
- Funny saying for any front-end developer, web developer, computer programmer, computer systems engineer, mobile app developer, software developer, or code lover who likes to code, make funny programming jokes, and take memorable photos.
- Wear it proudly at International Programmers' Day, school, coding classes, or coding communities! It also makes a funny present for a computer programming lover friend.
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
Unexpected header-only repeats
Open every page around the first failure. A header that appears at the bottom with no following data row indicates a pagination decision, not necessarily a CSS typo. Try a small margin adjustment, remove competing break rules, and test the candidate thead declarations in the minimal file before applying them to the full report.
A repeatable diagnostic procedure
- Capture the environment. Save
wkhtmltopdf --version, operating system, wrapper/library version, command-line flags, print-media setting and the exact input URL or file. - Mark the first bad page. Compare the last correct page, the first overlapping page and the next page. Note whether the header overlaps text, leaves a gap, or appears without a row.
- Minimize. Remove scripts, images, nested layout, responsive wrappers and nonessential columns until the symptom either remains or disappears.
- Verify semantics. Restore a clean
thead/tbodystructure and remove unnecessary rowspans and colspans. - Test the wrapper. Remove responsive overflow and flex parents, then test print-only block and overflow-visible rules.
- Choose the header policy. If repeats are unnecessary, test
display: table-row-group. If repeats are required, testtable-header-groupwith both break-avoidance declarations. - Regenerate with the deployed binary. Do not validate only in a browser or with a different wkhtmltopdf executable.
- Keep the fixture. Store the smallest failing or formerly failing HTML and compare generated PDFs after upgrades, template edits and CSS changes.
Common symptoms and targeted fixes
| Symptom | Likely area to test | Trade-off |
|---|---|---|
| Header overlaps the first body row | Repeating thead, wrapper overflow, flex parent, or boundary row |
Fixes can alter spacing or width |
| Header does not repeat | thead changed to table-row-group or malformed table structure |
Column labels disappear on later pages |
| Large blank area before a row | page-break-inside: avoid, tall row, or rowspan |
Removing the rule may split a row |
| Header repeats with no data beneath it | Pagination edge case or competing break rules | Margin and layout changes may move content |
| Works locally, fails in production | Different binary, OS, wrapper, flags or print-media mode | Requires environment-specific regression testing |
Reliability and maintenance considerations
The upstream wkhtmltopdf GitHub repository was archived on January 2, 2023 and is read-only: https://github.com/wkhtmltopdf/wkhtmltopdf. Historical issue discussions remain useful troubleshooting leads, but they are not current support commitments or cross-version guarantees. The reports describe different contexts rather than one confirmed root cause. Pin the executable used by your service, record its checksum or package version, and render representative PDFs in CI. Include short, long and rowspan-heavy tables, because a fix for one shape can fail at another page boundary.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your goal is a dependable screenshot or PDF capture rather than maintaining wkhtmltopdf pagination CSS, ScreenshotNeo provides a website screenshot API and MCP server. A single request can capture a clean PNG, JPEG, WebP or PDF, while its browser accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing status.
Use the API documentation at https://screenshotneo.com/docs/ for all options, including full-page lazy-image loading, CSS-selector element capture, custom CSS and JavaScript, waits, request blocking, headers and cookies, device and viewport controls, PDF page ranges, signed links, asynchronous jobs and bulk capture.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
r.raise_for_status()
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}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));ScreenshotNeo’s MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients. The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.
Best Value
- Programming Language Lover Code Apparel. App or Web Design and Development Expert Funny Dress. Best Valentines Idea For Coding Lover. HTML Code or Meaning Costume
- Funny I Know HTML - How To Meet Ladies Computer Programmer Quotes
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
Frequently asked questions
Is this a guaranteed wkhtmltopdf bug fix?
No. The documented reports involve different templates and environments, and the archived upstream project provides no current cross-version guarantee. Test the exact binary and PDF.
Can I keep repeating headers without changing HTML?
Sometimes. First test the print CSS and surrounding wrappers; if the minimal case still fails, simplifying rowspans or splitting complex tables may be necessary.
Should I switch PDF engines immediately?
Not necessarily. Establish a minimal reproduction and the required header behavior first. A pinned wkhtmltopdf fixture tells you whether a renderer change actually improves your documents.
Recommended Free Tools
Quick Recap
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.
