Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Set a finite navigation timeout and choose a page-ready condition that fits your site before calling the PDF generator. If navigation fails, catch the error and stop or report that job rather than waiting indefinitely. The exact control depends on the converter: Playwright and Puppeteer separate browser navigation from PDF creation, while wkhtmltopdf lets you choose whether a page-load error aborts, is ignored, or is skipped.
First identify which part is failing
“The PDF conversion is stuck” can describe two different stages: the browser has not reached the chosen navigation milestone, or the navigation finished and the PDF-writing call is taking too long or failing. Treat these as separate operations. In Puppeteer’s documented example, code navigates to a URL and then calls page.pdf(); its guide says, “By default, the Page.pdf() waits for fonts to be loaded.” That font behavior is part of PDF generation, not a reason to use an unlimited navigation wait. Playwright likewise exposes navigation waiting separately from PDF creation. wkhtmltopdf instead provides command-line settings for load errors.
Before changing a setting, record the converter and version, the exact error text, the URL or a reproducible example, and whether the failure is on the page itself or on an image, stylesheet, font, or other resource. The right fix depends on that distinction; these settings are not interchangeable.
Recommended Free Tools
Quick decision guide
| Tool | What to change | When it fits |
|---|---|---|
| Playwright | Navigation wait condition, finite timeout, or abort signal | You need to bound or cancel browser navigation and decide what “ready” means. |
| Puppeteer | Navigation wait condition and timeout before page.pdf() |
You want to control when the browser proceeds to PDF generation. |
| wkhtmltopdf | --load-error-handling and, separately, --load-media-error-handling |
You need to decide whether a failed page or failed media prevents conversion. |
Choose what “page ready” means
A browser can report several navigation milestones. The correct one is the earliest point at which the content you need for the PDF is actually present—not automatically the latest possible event.
#1 Best Overall
- Convert your PDF files into Word, Excel & Co. the easy way
- Convert scanned documents thanks to our new 2022 OCR technology
- Adjustable conversion settings
- No subscription! Lifetime license!
- Compatible with Windows 11, 10, 8.1, 7 - Internet connection required
commit: the navigation has committed. This is an early milestone and does not establish that the document content is ready for capture.domcontentloaded: the initial document has been parsed. It may be sufficient for a mostly static page, but images or application data may still be loading.load: the document’s load event has fired. This can wait for more page resources than DOM readiness.networkidle: the browser has reached a network-quiet state. Playwright discourages using this as a universal readiness check; pages with polling, analytics, or other continuing requests may never become idle.
For application pages, a domain-specific signal is often clearer: wait for a selector that only appears when the report or receipt is rendered, or use a web assertion that verifies the content you need. A fixed delay can help when a known, short transition needs time, but it is not proof that the page loaded correctly. If a page is consistently slow, first find out whether it is waiting on the document, an application request, or an optional resource.
Playwright: bound navigation and cancel it when needed
Playwright’s documented navigation timeout is zero by default unless configured, so a job that must have a maximum wait should set one explicitly. You can configure a default through page or browser-context methods, or set the timeout for a particular navigation. A navigation can also receive an AbortSignal; aborting the signal aborts that operation and throws an error. The example below uses a per-navigation timeout and demonstrates explicit cancellation. It assumes Node.js and an installed Playwright package; replace the URL with the page to convert.
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch({ headless: true });
try {
const page = await browser.newPage();
const controller = new AbortController();
const cancelAfterMs = 20_000;
const cancelTimer = setTimeout(() => controller.abort(), cancelAfterMs);
try {
await page.goto('https://example.com', {
waitUntil: 'domcontentloaded',
timeout: 15_000,
signal: controller.signal,
});
clearTimeout(cancelTimer);
await page.pdf({ path: 'page.pdf', format: 'A4' });
console.log('Saved page.pdf');
} catch (error) {
clearTimeout(cancelTimer);
console.error('Navigation or PDF generation failed:', error.message);
process.exitCode = 1;
}
} finally {
await browser.close();
}
})();The 15-second navigation timeout is an example policy, not a universal recommendation. Choose a limit based on the response time your application can tolerate. The 20-second abort illustrates cancellation if a longer-running navigation needs an external stop condition; because the navigation also has a 15-second timeout, the per-navigation timeout will normally be reached first. For a single deadline, set the timeout and cancellation policy consistently rather than adding a timer that cannot improve it. The catch handles the documented thrown error and allows the caller to mark the job failed. Closing the browser in finally prevents a failed job from leaving that browser instance open.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #2
![Doxillion Free Document Converter – Converts DOCX, DOC, PDF, WPS and Many More Files Quickly [Download]](https://m.media-amazon.com/images/I/81tjL48MwxL.png._SL160_.png)
- Convert over 50 document file formats.
- Preview your files from Doxillion before converting them.
- Use batch conversion to convert thousands of files at once.
- Enjoy an easy-to-use, intuitive interface with a Drag and Drop file option.
- Burn your converted or original files directly to disc.
If you change the wait condition to load or networkidle, do so for a reason tied to the page. Waiting for network idle is not a reliable universal remedy for a page that keeps making requests. If navigation succeeds but the output is incomplete, wait for a meaningful selector or assertion before generating the PDF instead of raising the timeout without diagnosis.
Puppeteer: stop waiting before calling page.pdf()
Puppeteer’s documented workflow also separates navigation from PDF creation. Set a finite navigation timeout and a deliberate waitUntil condition on page.goto(), then call page.pdf() only after navigation succeeds. This example uses Node.js and assumes Puppeteer is installed:
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.goto('https://example.com', {
waitUntil: 'domcontentloaded',
timeout: 15_000,
});
await page.pdf({ path: 'page.pdf', format: 'A4' });
console.log('Saved page.pdf');
} catch (error) {
console.error('Navigation or PDF generation failed:', error.message);
process.exitCode = 1;
} finally {
await browser.close();
}
})();The timeout shown is an example. If goto() rejects, execution enters the error handler and does not proceed to the PDF call. If navigation succeeds but the PDF call fails, the same handler reports that failure; inspect the error to identify which stage needs attention. Puppeteer’s documented default of waiting for fonts in page.pdf() means a delay after navigation may be associated with font readiness during PDF generation, rather than a navigation hang. Keep those stages distinct while diagnosing it.
Rank #3
- EDIT text, images & designs in PDF documents. ORGANIZE PDFs. Convert PDFs to Word, Excel & ePub.
- READ and Comment PDFs – Intuitive reading modes & document commenting and mark up.
- CREATE, COMBINE, SCAN and COMPRESS PDFs
- FILL forms & Digitally Sign PDFs. PROTECT and Encrypt PDFs
- 1 Year License for 1 Windows & 2 Mobile (Android and/or iOS) devices.
wkhtmltopdf: choose a page-load error policy
wkhtmltopdf makes the page-load decision explicit with --load-error-handling. Its documented choices are abort, ignore, and skip; the default is abort. The appropriate choice depends on whether a PDF made from a partially failed page is useful in your workflow.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →# Fail the conversion when the page itself has a load error (documented default)
wkhtmltopdf --load-error-handling abort https://example.com page.pdf
# Continue despite a page-load error
wkhtmltopdf --load-error-handling ignore https://example.com page.pdf
# Skip pages with a page-load error
wkhtmltopdf --load-error-handling skip https://example.com page.pdfUse abort when a partial or misleading PDF is worse than a failed job. ignore and skip change the outcome rather than repairing the page: conversion may proceed or omit affected pages even though a load error occurred. Verify the resulting PDF is acceptable before treating either setting as a successful recovery.
Media failures have a separate control, --load-media-error-handling, documented with the same values and a default of ignore. This applies to media resources, not the page’s main load error. For example, choose a media policy deliberately if the HTML loads but an image or other media resource does not. Changing the media setting will not, by itself, resolve a failed page navigation.
Rank #4
- Perfect Adobe Acrobat Pro alternative – lifetime license for Windows 10 and 11.
- EDIT text, images, pages, hyperlinks, designs in PDF documents. ORGANIZE PDFs.
- READ and Comment on PDFs – Intuitive reading modes & document commenting and mark up tools!
- CREATE, COMBINE, SCAN and COMPRESS PDFs.
- FILL forms & Digitally Sign PDFs. Work with Digital certificates
# Example: abort on page errors, but retain the documented media default
wkhtmltopdf --load-error-handling abort https://example.com page.pdf
# Example: explicitly ignore media load errors
wkhtmltopdf --load-media-error-handling ignore https://example.com page.pdfDo not use script settings to mask a load failure
wkhtmltopdf also documents a JavaScript delay and a setting to stop slow scripts. These affect post-load or script behavior; they are not substitutes for identifying a network or navigation failure. A longer delay may let a known client-side rendering step finish, but it cannot make an unreachable document load. Stopping a slow script can change page behavior and may leave the rendered content incomplete. First establish whether the document loaded and whether the required content appeared; adjust script timing only when the failure is actually in that stage.
Common symptoms and the next check
- Navigation waits without a clear end: Set a finite navigation timeout in Playwright or Puppeteer. Check the chosen readiness condition and use an application-specific signal if the page does not settle. In Playwright, use an abort signal if the caller must actively cancel the navigation.
- It fails at the full-load or network-idle wait: Try an earlier milestone only if it is sufficient for the PDF’s content. For a page that continuously requests resources, Playwright’s documentation discourages relying on network idle as a general readiness test.
- The page loads but images or other media are missing: With wkhtmltopdf, inspect the separate media-error policy. A media setting will not fix a main-page load failure.
- wkhtmltopdf exits rather than producing a PDF: Its documented page-load default is
abort. Decide whether the job should fail, proceed despite the page error, or skip affected pages; do not choose a permissive mode unless a partial result is acceptable. - Navigation finishes but PDF creation still fails or stalls: Capture the exact error and identify whether it comes from
page.pdf(). Do not assume that changing navigation wait behavior will fix a PDF-generation problem. Puppeteer’s default font wait is relevant to the PDF stage. - A longer JavaScript delay appears to help: Confirm that required content is actually rendered and that the underlying problem is script timing. A delay is not a general fix for a network or navigation error.
Or skip the browser setup
ScreenshotNeo is a website screenshot API that can return PNG, JPEG, WebP, or PDF. Its PDF options include paper size, margins, landscape orientation, and page ranges. It can accept a URL in one GET request; consult the API documentation for the PDF request parameters and output settings. The sample below is the supplied one-call screenshot example; it saves a WebP screenshot, not a PDF:
Free tools Windows power users keep installed
One-click scans. No signup required.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython equivalent:
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 equivalent:
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 accepts cookie and consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in X-Page-Verdict and X-Billed headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients. Free includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots, and all features are on every plan.
Sign up free for 1,000 screenshots a month with no card.
Best Value
![Doxillion Free Document Converter for Mac – Converts DOCX, DOC, PDF, WPS and Many More Files Quickly [Download]](https://m.media-amazon.com/images/I/51Xjwhv3w2L._SL160_.jpg)
- Convert over 50 document file formats.
- Preview your files from Doxillion before converting them.
- Use batch conversion to convert thousands of files at once.
- Enjoy an easy-to-use, intuitive interface with a Drag and Drop file option.
- Burn your converted or original files directly to disc.
Reliability and cost: fail fast, then decide what result you can accept
A finite wait makes the failure visible and gives the calling job a point at which to report, retry, or stop; it does not make a broken source page healthy. Choose a timeout that fits the job’s operating limit and readiness condition that corresponds to its output requirements. Do not retry indefinitely: if you retry, make the retry policy explicit in the caller and preserve the first error so repeated timeouts are diagnosable.
For wkhtmltopdf, the choice between aborting and continuing is also a data-quality decision. A conversion that exits successfully after ignoring a load failure may still be incomplete. Conversely, a missing optional media asset may not justify failing the whole document. Keep page-load and media-load policies separate, and validate output against the content your workflow requires.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteWhat to include when escalating a failure
If finite waits and the tool-specific settings do not resolve the problem, share details that identify the stage rather than reporting only that “PDF conversion hangs.” Include:
- Converter name and installed version, plus operating system and how the converter is invoked.
- The exact error text and whether it occurred during navigation, a wait for a selector, or PDF generation.
- The selected readiness condition and timeout, or the wkhtmltopdf page/media error settings.
- Whether the page itself failed, only a resource failed, or the page rendered but the PDF was incomplete.
- A minimal reproducible URL or sanitized HTML and the expected versus actual output.
Those details matter because this is a cross-tool troubleshooting pattern, not a diagnosis of a particular exception, wrapper, service, or deployed version. The Playwright, Puppeteer, and wkhtmltopdf interfaces can change; match examples and options to the version you have installed.
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.
