How to Fix CloudConvert HTML to PDF Jobs That Show a Blank Page

A CloudConvert job marked finished does not prove that its PDF contains visible content. Check the source and capture task first, then determine whether content appears after JavaScript runs, whether the remote browser can access the page and its dependencies, and whether the exported PDF actually contains visible pages.

CloudConvert describes its HTML-to-PDF service as using headless Chrome. It accepts a URL or HTML file, and its website capture operation is capture-website. For URL captures, the operation requires a URL and output format; its options include an engine, engine version, and timeout. CloudConvert also describes a feature that waits for a custom CSS selector. Check the current Job Builder or operation reference for the exact selector-wait payload before using it, because the reviewed reference material does not establish the current key and syntax. CloudConvert HTML to PDF · Website capture operation

1. Confirm the input and operation

Start with the job definition, not the PDF layout. Make sure the source you intended to capture is the source actually being processed.

For a web page, confirm the URL is correct, including its scheme, path, query string, and any redirect destination.
Confirm the website-capture task uses capture-website and requests pdf as its output format.
Confirm an export task takes the capture task’s output as its input.
For an uploaded HTML file, verify that the intended file was imported and connected to the supported HTML-to-PDF workflow.
Use CloudConvert’s Job Builder to generate a payload for the exact input and output combination. Operation options and their syntax can change.

CloudConvert jobs are groups of named tasks, commonly an import, a conversion or capture, and an export. Inspect each task, rather than relying on the top-level job status. CloudConvert jobs and tasks

2. Check whether the page has content when capture begins

A page can return its initial HTML before its useful content appears. JavaScript may fetch data, build the main interface, or reveal content only after an interaction. A capture that begins too early can therefore produce a PDF without the content you see in your normal browser.

Open the page in a private browser window and note whether it redirects, asks for sign-in, or initially shows a loading state.
Inspect the page after it settles. Identify a selector that belongs to the actual content, such as the main report container, rather than a generic page shell.
If the content appears asynchronously, configure CloudConvert’s documented custom CSS selector wait. Verify the current option name and value syntax in the Job Builder or current operation options.
Try a small static HTML page with visible text and no scripts or remote assets. If that works but the original does not, the issue is likely in the original page’s runtime behavior or dependencies. This is an isolation test, not a CloudConvert diagnosis.

CloudConvert says its headless Chrome browser can wait for a custom CSS selector to appear. That is useful when the page’s meaningful content arrives after initial load; it does not guarantee that a selector exists or that the content beneath it is visible. HTML-to-PDF options

3. Check access to the URL and its dependencies

Your browser and a remote conversion service may not have the same access. Check for redirects, authentication, session-dependent content, and resources loaded from other hosts.

Check whether the URL requires a logged-in session or relies on cookies set during an earlier navigation.
Check whether the page redirects to a sign-in page, access-denied screen, or bot check when opened without your normal browser session.
Check whether fonts, images, stylesheets, scripts, and API responses come from hosts that the remote browser can reach.
If the resource is protected, consult CloudConvert’s current documentation for supported custom headers and configure authorization only when appropriate for that resource.

CloudConvert documents custom Authorization headers for protected resources. This makes access worth checking; it does not establish that every cookie-based or session-based login flow is supported. Do not put credentials into a public URL or expose long-lived secrets in client-side code.

4. Inspect every task and its result

Read the job response and inspect the individual tasks. Record each task’s operation, status, result files, and error details. CloudConvert documents task states including waiting, processing, finished, and error. By default, a task error fails the job unless that task is configured to ignore an error.

A finished capture task means that task completed according to the API workflow. It does not establish that a human can see content in the resulting PDF. Treat visual inspection as a separate diagnostic step.

CloudConvert supports asynchronous jobs and webhooks, as well as synchronous endpoints. A timeout in your client or network stack while waiting does not by itself show that rendering failed. Retrieve the job’s current state before retrying a capture that may still be running. CloudConvert API quickstart · Job and task states

5. Check the PDF layout only after confirming content exists

If the PDF is not truly empty but content is clipped, outside the printable area, or hard to see, compare the capture’s page dimensions, margins, zoom, and any custom headers or footers. CloudConvert documents these layout controls, but the available evidence does not identify any one setting as a general fix for a genuinely blank PDF.

Compare the rendered page with the browser viewport and the document’s expected print layout.
Check whether the page or its print stylesheet sets white text on a white background, hides content for print, or positions content outside the page.
Change one layout option at a time and keep a record of each attempt.
If you choose an engine or engine version, use only options currently offered for the operation.

Do not use zoom, margins, or page size as a substitute for checking whether the source rendered the content at all. Those controls can change where visible content lands; they cannot make inaccessible or never-rendered content appear.

6. Download and inspect the exported file

Confirm that the export task returned the expected file, download that exact result, and inspect it independently of the job status. Check the page count and open each page in a PDF viewer. If available in your workflow, render the PDF pages to images so you can distinguish an empty page from a viewer display issue.

Keep the job identifier, task details, source URL or input file, capture options, exported file, and a screenshot of the source page at the time of capture together. That gives you a reproducible comparison if the issue appears again.

Quick diagnostic checklist

Wrong or incomplete source: verify URL or HTML input, capture operation, output format, and export input.
Content appears late: use a selector tied to the real content and confirm its current option syntax.
Protected page: check redirects and authorization requirements from the remote browser’s perspective.
Task did not complete: inspect task-level status and error details; refresh job state after a client timeout.
File workflow completed: download and inspect the exported PDF separately.
Content exists but looks missing: investigate print CSS, color contrast, page size, margins, and zoom one at a time.

Common errors and what to do

Symptom or response	What it tells you	Next step
Job or task is `error`	A task failed; the job status and task details identify where.	Inspect the failing task’s error details and input. Fix that failure before diagnosing the PDF’s visual content.
HTTP `422`	CloudConvert documents this as an invalid-data response.	Check the job payload against the current operation schema and use the Job Builder to confirm supported fields and values. API reference
HTTP `429`	The API is rate-limiting the request; some endpoints use dynamic rate limits.	Follow the response’s `Retry-After` value before retrying. Avoid an immediate retry loop. API reference
Caller timed out, job still processing	The caller stopped waiting; that does not establish that the remote job failed.	Fetch the job’s current status or use the configured asynchronous completion flow before submitting another job.
Task finished, exported PDF appears blank	The task completed, but visual correctness has not been established.	Check input, delayed rendering, access, and dependencies, then inspect the downloaded PDF.
PDF has a page, but content is clipped or invisible	Content may have rendered outside the page or with unsuitable print styling.	Inspect print CSS and test page dimensions, margins, zoom, or colors one at a time.

Performance, reliability, and cost considerations

CloudConvert exposes a timeout setting for website capture. A longer timeout can give a slow page more time, but it cannot fix a URL the service cannot access or content that never appears. A selector wait can target readiness more directly when the page has a reliable content element. Keep job handling asynchronous when rendering may outlast the caller’s request window, and inspect existing job state before retrying.

No reviewed source provides a blank-page incidence rate, a universal best timeout, or a cost figure for the specific workflow. Check your account’s current pricing and limits directly before estimating cost. Distinguish API errors and unfinished tasks from a completed job whose exported file simply needs visual inspection.

Or skip the browser setup

If your goal is a screenshot of a web page for debugging or documentation, ScreenshotNeo is a website screenshot API and MCP server. A single GET request returns an image or PDF, without building and maintaining your own browser capture setup. For a specific CloudConvert blank-PDF job, continue to inspect the CloudConvert task and export; ScreenshotNeo is an alternative capture workflow.

Example request for a screenshot:

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

Equivalent Python request:

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)

Equivalent Node.js request:

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(`ScreenshotNeo returned HTTP ${res.status}`);
const bytes = new Uint8Array(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', bytes));

See the ScreenshotNeo API documentation for request options. Cookie banners, popups, and chat widgets are removed before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000 shots.

FAQ

Does a finished CloudConvert job guarantee a visible PDF?

No. Check the task results and inspect the exported PDF itself to confirm what it contains.

Can I use a CSS selector wait for JavaScript-rendered content?

CloudConvert documents a custom selector wait. Verify its current payload syntax in the Job Builder or operation options, and choose a selector tied to the content you need.

Should I increase the timeout to fix a blank page?

Only if evidence suggests the page needs more time to load. A longer timeout cannot resolve missing access, failed dependencies, or content that never renders.

Why does the page look right in my browser but not in the PDF?

Your browser may have a session, cookies, cached resources, or a different rendering state. Compare redirects, authentication, dependencies, and delayed content from the capture service’s perspective.

Where do I find the exact selector-wait payload?

Use the current CloudConvert Job Builder or operation options. The syntax can vary, and it should be checked before copying a payload into production.