Start by inspecting the element that should begin the new page and its ancestors. In wkhtmltopdf, unexpected whitespace after page-break-before is usually caused by a floated or overflowing parent, a broad page-break-inside: avoid rule moving content, print-only CSS, or conflicting margins and page geometry—not by a missing second page-break declaration. Reproduce the PDF with the deployed wkhtmltopdf binary, make one focused CSS change at a time, and compare the affected two pages.
Why a forced break can leave a gap
wkhtmltopdf uses an older WebKit pagination model. The wkhtmltopdf man page says WebKit lays the document out as one long page and then cuts that layout into pages; it also warns that “The current page breaking algorithm of WebKit leaves much to be desired.” A forced break therefore interacts with normal flow, ancestor formatting contexts, margins, and rules that try to keep content together.
The same CSS can paginate differently between operating systems, Qt builds, and wkhtmltopdf versions. The reports commonly cited for this symptom cover 0.12.0, 0.12.1, 0.12.2.1, and 0.12.6, so treat each workaround as a hypothesis to test on your production binary rather than a universal fix.
First, capture a reproducible case
- Record the exact
wkhtmltopdf --versionoutput, operating system, whether Qt is patched, page size, PDF margins, and every command-line option. - Save the HTML, all stylesheets, fonts, images, and the command used to render it. Confirm that the print stylesheet and any
@media printrules are actually loaded. - Render the same input twice without changing CSS. If the gap moves or changes, investigate external resources, JavaScript timing, or a cache rather than pagination rules alone.
- Create a minimal copy containing the break target and only the ancestors and styles needed to reproduce the gap. Keep the full production page as a control; reducing markup can remove the very dependency that triggers the bug.
A useful test command is:
wkhtmltopdf --print-media-type --margin-top 15mm --margin-bottom 15mm input.html output.pdfUse the options your application actually deploys. A community report about --print-media-type concerns one 0.12.0 setup and does not establish that the flag is required for every build. Verify the result on your own binary.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problems#1 Best Overall
Inspect the break target and its ancestors
Remove a floated parent temporarily
Issue #2371 documents a case where page-break rules worked when the parent was in normal flow but were ignored when that parent had float:left. The reporter solved that layout by disabling the float in PDF-specific CSS:
@media print {
.report-column {
float: none;
width: auto;
}
}
.chapter {
page-break-before: always;
}Apply float:none only to the affected ancestor. Check that the change does not alter column widths, overlap content, or move unrelated blocks. If the break starts working and the gap disappears, replace the float with normal flow or a print-only layout that preserves the intended width.
Test overflow on the containing block
The same issue discussion includes a report of similar behavior with overflow:auto and a suggestion to try overflow:visible. This is an issue comment, not a guarantee. Test the smallest possible scope:
@media print {
.report-shell {
overflow: visible;
}
}Look for clipping after the change. An overflow container may have been hiding a deliberate crop or creating a new formatting context; remove it only when the PDF layout still fits the page.
Check hidden margins, padding, and line boxes
Inspect the last element on the previous page and the first element after the break. A bottom margin on the former, top margin or padding on the latter, a large line-height, or an explicit height can look like whitespace “after” the break. Compare computed values in your browser’s print emulation and then verify the generated PDF, because wkhtmltopdf does not implement modern browser layout identically.
@media print {
.before-break {
margin-bottom: 0;
padding-bottom: 0;
}
.chapter {
margin-top: 0;
padding-top: 0;
page-break-before: always;
}
}Do not remove spacing globally. Scope the reset to the component whose geometry you measured.
Audit page-break-inside and related rules
A broad page-break-inside: avoid can preserve a block or table row by moving the entire item to the next page. The moved item may leave a large blank region where you expected following content to flow. Issue #4868 describes this kind of unwanted table whitespace. Conversely, issue #4212 reports a different table-spacing problem where a combination of break-avoidance rules helped. These are layout-specific outcomes, not contradictory universal fixes.
Scope avoidance to content that must stay together
/* Avoid splitting only the small unit that must remain intact. */
.invoice-total,
.signature-block {
page-break-inside: avoid;
}
/* Do not apply this to every row or wrapper unless you have tested it. */
.large-table-row {
page-break-inside: auto;
}For a large table, test the row, table, and wrapper separately. If a row is taller than the remaining page, avoiding a split necessarily creates unused space; no break rule can fit it without either moving it or splitting it.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Use before, after, and inside as a coordinated set
When a component must stay together, define its rule on the component rather than on every ancestor:
.appendix {
page-break-before: always;
page-break-inside: avoid;
page-break-after: auto;
}Then test a version with only page-break-before. If the gap appears only when avoidance is enabled, the avoidance rule is consuming the space by moving a block. If the break is ignored only inside a particular wrapper, return to the float and overflow checks.
Verify print styles and page geometry
Confirm the active media and build
Print CSS may differ from screen CSS in display, width, positioning, floats, and visibility. Confirm that the stylesheet containing your break rule is loaded and that its selector wins the cascade. A rule in a later or more specific stylesheet can silently override it.
Keep page geometry consistent while diagnosing: paper size, orientation, top and bottom PDF margins, CSS page margins, and any fixed header or footer. Change one value at a time. An isolated suggestion to alter page size is not a first-line fix for every gap.
Recommended Free Tools
Check dimensions that force a move
- Fixed heights on wrappers or table cells can reserve space that appears blank.
- Absolutely positioned headers, footers, or backgrounds can overlap the normal flow or make a page look empty.
- Images and long unbroken text can expand after resources load, changing where the break lands.
- A block that cannot fit in the remaining space may be moved intact, especially when an ancestor uses
page-break-inside: avoid.
A focused troubleshooting workflow
- Baseline: render the deployed HTML and save the PDF, version output, command, and page containing the gap.
- Reduce: reproduce with the break target and its necessary ancestors; keep a copy of the complete page.
- Test flow: set the suspected floated ancestor to
float:none, render, and compare. Revert if unrelated layout changes. - Test overflow: change only the affected ancestor from
overflow:autoor another clipping value tooverflow:visible, then check for clipping. - Test avoidance: remove broad
page-break-inside: avoidrules, then add them back only to small blocks that must remain intact. - Test spacing: inspect margins, padding, line-height, fixed dimensions, and PDF margins around both sides of the break.
- Test media: render with the production print-media setting and, separately, with the alternate setting used by your deployment. Record the difference rather than assuming one flag is universally correct.
- Compare: inspect the page before the break and the page after it for clipping, overlap, split rows, and missing images—not just the size of the blank area.
| Symptom | First test | Success criterion |
|---|---|---|
| Break ignored inside a column | Disable float on the affected parent in print CSS |
The target begins on a new page without changing unrelated columns |
| Large blank area before a table row | Remove broad page-break-inside: avoid |
Whitespace falls without splitting content that must remain together |
| Gap changes with print options | Compare the deployed media flag and recorded wkhtmltopdf build | One documented configuration reproduces consistently |
| Content is clipped after an overflow change | Revert the change and isolate the smallest overflow ancestor | The break is fixed without hiding content |
| Spacing remains after CSS fixes | Audit PDF margins, CSS margins, padding, fixed heights, and loaded assets | The remaining space has an identified geometric cause |
Common errors and recovery steps
“I added another page-break rule, but nothing changed.”
Additional breaks do not override a floated formatting context, an ancestor that clips overflow, or a block moved intact by avoidance rules. Remove the extra declaration, identify the constraint, and test that constraint directly.
“Removing page-break-inside: avoid caused split rows.”
Restore avoidance only for rows or blocks that genuinely require it. If a single item is taller than a page, redesign that item, allow a controlled split, or accept that moving it leaves unused space.
“The browser preview is correct, but the PDF is not.”
Browser print preview and wkhtmltopdf use different engines and pagination algorithms. Compare the exact production binary, Qt build, operating system, options, and loaded assets. Treat browser behavior as a clue, not proof.
Rank #4
- Includes Bonus CD
“The fix works locally and fails in deployment.”
Capture the deployed version and command first. A patched-Qt Windows build and another platform may paginate differently. Pin and document the renderer configuration that produces an acceptable PDF, and keep the minimal reproduction in your test suite.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Maintenance considerations
The wkhtmltopdf repository pages for these issues show an archive/read-only notice dated January 2, 2023. That does not identify a replacement renderer or prove that migration will solve this particular gap. If the layout cannot be stabilized, evaluate alternatives against your HTML/CSS features, runtime constraints, security requirements, and maintenance burden using each candidate’s current primary documentation.
For every workaround you keep, document the affected selector, renderer version and Qt build, operating system, page settings, expected page location, and the regression you are preventing. Re-render representative tables, images, long blocks, and the exact production template after upgrades.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your actual goal is a clean image of a web page rather than a wkhtmltopdf PDF, ScreenshotNeo provides a single HTTP request. It is not a wkhtmltopdf replacement for generating paginated PDFs, but it avoids maintaining a headless-browser capture pipeline for PNG, JPEG, or WebP screenshots. Before capture it accepts consent banners 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. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
Use the API endpoint and parameter names shown in the ScreenshotNeo documentation:
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Every plan includes the capture options, including full-page lazy-image loading, CSS-selector element capture, device presets or custom viewports, dark mode, retina scale, custom CSS and JavaScript, waits, request blocking, cookies and headers, timezone and geolocation, transparent backgrounds, resizing, configurable caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. The free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account to try it.
Best Value
- Used Book in Good Condition
Decision checklist
- Have you reproduced the gap with the production wkhtmltopdf binary and exact command?
- Did you test the floated and overflow ancestors before changing global break rules?
- Is
page-break-inside: avoidscoped to content that must stay together? - Did you verify print media, margins, padding, fixed dimensions, and loaded assets?
- Did you compare both pages for clipping, overlap, and split content?
- Is the workaround documented with its version, platform, and regression case?
Frequently Asked Questions
Does adding page-break-after fix whitespace caused by page-break-before?
Not reliably. The gap is usually produced by an ancestor constraint or content being moved during pagination, so another break declaration can leave the underlying cause untouched.
Should I always set overflow: visible for PDFs?
No. That change is a test for a reported ancestor condition. Apply it only to the affected element and confirm that content is not clipped or overlapped.
Can wkhtmltopdf guarantee that a table row will never split?
No. Avoidance rules can move a row to the next page and leave blank space, while very large rows may not fit on one page at all.
Is ScreenshotNeo suitable when I need a paginated PDF?
ScreenshotNeo can capture screenshots and offers a PDF tool, but it is a separate service rather than a drop-in wkhtmltopdf pagination engine. Choose it when its capture workflow and controls match your output requirements.
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.
