How to Debug a Blank PDF from DocRaptor

If a DocRaptor PDF is blank, start with the job status and that document’s log. Compare the submitted HTML with the HTML after JavaScript processing, then inspect asset errors and the conversion stage. This separates a failed job from a job that completed but produced a blank-looking document—and gives you evidence before you change code.

1. Confirm whether the conversion job completed

A failed request and a completed PDF with no visible content are different problems. If you use asynchronous conversion, retrieve the job status before investigating page layout. A job may be queued, working, completed, or failed.

Record the document identifier returned for the conversion.
Check the job’s current status and any validation or error details.
If it failed, resolve the reported request or conversion error first.
If it completed, open the resulting PDF and the document log for that same identifier.

Do not treat an HTTP response or a queued job as proof that a finished, populated PDF exists. The status and the document-specific log are the evidence to follow.

2. Use the document log to locate the first missing step

The log is the best starting point because it can show the submitted input and parameters, the HTML after JavaScript processing, asset-loading errors, and the stage at which conversion failed or completed. Compare these in order:

Submitted HTML and options: Is the expected content present in the source you sent? Are you sending the intended document and conversion settings?
HTML after JavaScript processing: If the page builds content in the browser, is that content present in the processed HTML?
Asset errors: Did stylesheets, scripts, images, or fonts fail to load?
Conversion stage: Did generation complete, or does the log identify a failure before the PDF was produced?

This comparison narrows the investigation. If the source is already empty, inspect the application that creates it. If source content exists but processed HTML is empty, investigate script execution and timing. If the content is present but styling or images are missing, investigate resource access. If the log reports a pipeline failure, address that reported failure before changing document markup.

3. Check JavaScript-generated content and timing

DocRaptor JavaScript execution is disabled by default. If your document relies on JavaScript to insert text, render a chart, or populate a template, enable the documented JavaScript option for the request. Check the current API reference and the client library version you use for the exact option name and syntax.

Enabling JavaScript is not enough when the script does asynchronous work. A conversion can begin layout before a fetch, data load, or rendering callback has finished. Use DocRaptor’s documented completion mechanism or a suitable delay so the conversion waits for the work your page requires. Then inspect the post-JavaScript HTML in the log to confirm the expected content exists before layout.

If the processed HTML lacks the content, check script errors, data responses, selectors, and completion timing.
If the content is present there but absent in the PDF, investigate CSS visibility, page layout, and the conversion log’s later stages.
If scripts are not needed, leave JavaScript disabled; enabling it cannot repair empty source HTML or inaccessible assets.

4. Verify that every external resource is reachable

The conversion service must be able to fetch each stylesheet, script, image, and font referenced by the document. A URL that works in your browser may still be unavailable from DocRaptor’s conversion environment—for example, if it requires a local session, network access, or authentication that the service does not have.

Prefer absolute https:// URLs for external assets.
For relative paths, supply a usable base URL through the API or an HTML <base> element.
Check protocol-relative URLs such as //example.com/file.css; they still require a usable document scheme and a reachable host.
A URL pointing to localhost resolves from the conversion environment, not your development computer. Send document content directly, embed suitable resources, or expose the resource through a reachable test server.
Check protected resources separately. If an asset requires authentication, ensure the conversion request can access it using the supported configuration.

Missing CSS can make present text appear invisible or badly positioned; missing fonts or images can make a document incomplete. Use the log’s asset errors to distinguish those cases from absent HTML.

5. Surface resource errors during diagnosis

DocRaptor generally ignores resource errors by default. That can let conversion finish while omitting a resource that the page needs to display correctly. During diagnosis, consider setting the documented ignore_resource_errors option so resource failures cause generation to report an error instead of passing silently.

Confirm the exact spelling and support in the API reference and the client library version you are using before changing a production request. Treat this as a diagnostic setting: once you have found and fixed the underlying resource problem, restore the error-handling behavior your application intends to use.

6. Reproduce the document with a small checklist

After locating a likely cause, reduce the document to the smallest input that still reproduces it. This helps separate application data and resource problems from conversion configuration.

Start with literal HTML containing a visible heading and paragraph.
Convert it with the same API path and record the job identifier and status.
Add the stylesheet and other resources back one at a time, checking the log after each change.
Add JavaScript only if the document needs it, and verify the processed HTML contains the generated content.
Restore the full document and request options in small groups until the issue returns.

This is a diagnostic method, not a guarantee that a minimal example will reproduce every environment-specific access or timing issue. Keep the original request and its log available for comparison.

7. Troubleshooting common blank-PDF symptoms

Symptom	Likely branch to inspect	Next action
The job is failed, not completed	Validation or conversion failure	Read the status and error details first; fix the reported request or pipeline problem before debugging the finished PDF’s appearance.
The submitted HTML is empty or missing expected data	Input generation or wrong document	Inspect the exact payload and document identifier. Fix the upstream template or data selection.
The source has content, but processed HTML does not	JavaScript disabled, errored, or unfinished	Enable JavaScript if required, handle asynchronous completion, and inspect processed HTML again.
Text exists but looks invisible or unstyled	Stylesheet did not load, or CSS hides the content	Check asset errors and CSS rules such as `display: none`, zero opacity, white text on a white background, or off-page positioning.
Images, fonts, or some sections are missing	External URL is unreachable or relative path has no base	Use an absolute reachable URL or set a base URL; check authentication and localhost references.
Conversion succeeds despite missing dependencies	Resource errors may be ignored	Temporarily enable the documented resource-error behavior and inspect the reported error details.
It works locally but not in DocRaptor	Different network, filesystem, session, or timing context	Check every dependency from the conversion environment’s perspective; do not rely on local files or browser-only session state.
The log does not identify the cause	Document-specific conversion issue	Submit a Help Request from that document’s log so DocRaptor support can inspect the document and its conversion details.

8. Escalate with useful evidence

If the log and a reduced reproduction do not isolate the problem, use the Help Request in the DocRaptor document log. DocRaptor says this allows its support team to access the content and help debug the document; the details view shows steps taken and problems encountered.

Include the document identifier, whether the job completed or failed, the relevant log observations, and a concise description of what should appear versus what the PDF contains. Never post API credentials in a public issue or include secrets in a reproduction.

Or skip the browser setup

If your goal is a screenshot or PDF of a web page rather than debugging a DocRaptor conversion, ScreenshotNeo is a website screenshot API and MCP server. It can return a screenshot or PDF from one GET request. See the ScreenshotNeo API documentation for options and configuration.

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

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)

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, then removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Performance, reliability, and cost considerations

For DocRaptor, use the log and a small reproduction to avoid repeated full conversions while investigating. Fix the first failing stage you can verify, then rerun the same document to confirm the result. This guide does not assume a particular conversion time, reliability rate, or cost: those depend on your request, document, and plan. Check your account and current DocRaptor documentation for applicable limits and pricing.

For web-page captures, ScreenshotNeo’s billing rules distinguish clean captures from bot checks, blank pages, failed loads, timeouts, and cache hits, which cost nothing. It offers caching with a configurable TTL, async jobs with signed webhooks, bulk capture of up to 100 URLs per call, and a usage API. Its listed plans are Free: 1,000 shots/month; Starter: $5 for 3,000; Growth: $15 for 15,000; Pro: $39 for 60,000; Scale: $99 for 250,000; Business: $249 for 1,000,000. Yearly billing gives two months free. Every listed feature is on every plan. These are ScreenshotNeo product details; they do not change how to diagnose a DocRaptor job.

FAQ

Can I fix a blank PDF by changing the paper size?

Only if the log and rendered content indicate a page-layout or clipping issue. First verify that the expected content exists in the submitted and post-JavaScript HTML and that the job completed.

Should JavaScript always be enabled for HTML-to-PDF conversion?

No. Enable it when the document depends on script-generated content. Otherwise, first inspect the source HTML and assets; JavaScript adds no value to static content.

Why does the PDF look blank when the conversion says it succeeded?

A completed conversion does not prove that the expected content was in the HTML at layout time or that its assets loaded. Compare the log’s source and processed HTML, asset errors, and conversion stage.

Can DocRaptor fetch files from my computer?

Not through a path that only exists on your computer. Send content directly, embed suitable resources, or make them reachable to the conversion service.