Why DocRaptor PDFs Have Missing Images and How to Fix Them

If a DocRaptor PDF is missing images, first check whether the renderer can resolve each image URL and reach the host serving it. Your browser and DocRaptor may not share a filesystem, network access, URL base, credentials, or rendering timing. A PDF job can also succeed while resource errors are logged and ignored. The steps below follow DocRaptor’s public documentation; they are diagnostic guidance, not a claim of hands-on testing.

Why are images missing from my DocRaptor PDF?

Start with the final HTML and CSS submitted to DocRaptor. For every missing image, determine the exact URL the renderer should request, whether that URL is reachable from DocRaptor’s rendering environment, and what the document log reports. Static images usually depend on URL resolution and access. Images inserted or loaded asynchronously by JavaScript also depend on JavaScript configuration and completion timing.

Resolve the URL. Prefer a fully qualified https:// URL, or supply a correct prince_options[baseurl] or HTML <base> element for relative paths.
Check reachability. A URL that works on your laptop, localhost, a VPN, or a private network may not be accessible to the renderer.
Read the document log. DocRaptor can log and ignore resource errors by default, so a successful job does not establish that every image loaded.
Check timing and JavaScript. If code creates the image or loads its URL asynchronously, ensure JavaScript is configured and the content is ready before rendering finishes.

DocRaptor’s troubleshooting documentation says it “has to know where on the internet to find all of your external assets.” See its PDF Generation Troubleshooting and API Reference.

How do I use relative image URLs with DocRaptor?

A relative reference such as ../images/photo.jpg needs a base URL. Without one, the renderer may not know which directory or site should contain the image. An absolute URL makes the target explicit at the point where the image is referenced. A base URL or a <base> element lets you keep relative references across the document.

Option 1: use an absolute URL

<img src="https://assets.example.com/invoices/photo.jpg" alt="Product photo">

Replace the example host and path with an address that DocRaptor can reach. Use the same check for CSS image references such as background-image: url(...).

Option 2: add an HTML base element

<head>
  <base href="https://assets.example.com/invoices/">
</head>
<body>
  <img src="photo.jpg" alt="Product photo">
</body>

With this base, photo.jpg resolves under the specified directory. A root-relative path such as /images/photo.jpg resolves from the domain root, not from the /invoices/ directory. Verify the resulting URL rather than assuming it inherits the base path you intended.

Option 3: provide the API base URL

For relative references in HTML sent through the API, set prince_options[baseurl] to the intended base URL. The exact request format depends on the API client you use; the important detail is that the base must identify the correct origin and, when needed, directory. Refer to the DocRaptor API reference for request parameter syntax.

Reference form	What to check
`https://host/path/image.png`	Explicit URL; confirm the host is reachable and the response serves the image.
`images/image.png` or `../image.png`	Requires an intentional base URL.
`/images/image.png`	Resolves from the domain root; check that this is the intended location.
`//host/path/image.png`	Protocol-relative; give the document a suitable base or make the scheme explicit.

DocRaptor identifies relative or protocol-less external asset URLs without a base as a common file-system access problem. See “File System Access is Not Allowed” and “Image, CSS or JavaScript file not loading?”.

Why do images show in my browser but not in the PDF?

The browser preview runs in your environment. DocRaptor fetches document assets from its rendering environment. An image may therefore appear in your browser but remain unreachable to DocRaptor if it comes from a local file path, localhost, a private IP, a VPN-only server, or a host protected by access rules.

Can DocRaptor load images from localhost?

Not from your computer’s localhost address as-is: that address refers to the machine making the request, and DocRaptor’s renderer is separate. DocRaptor says document and asset URLs need to be publicly accessible. For local development, its documentation describes these approaches:

Submit the HTML as document_content. This avoids requiring DocRaptor to fetch the HTML document itself. Linked images still need to be reachable separately.
Temporarily expose a development server through a tunnel. This can make local assets reachable during development. Keep the tunnel available while the PDF is generated.
Embed image bytes as Base64. Embedding removes the separate image fetch, at the cost of increasing the HTML payload.

These are development options, not interchangeable guarantees: sending HTML content alone does not expose images linked from localhost. Details are in Development Testing & Localhost Servers.

Remote image URLs or Base64 data?

Approach	Useful when	Trade-off
Remote URL	The asset host is accessible to DocRaptor and you want a smaller HTML payload.	Rendering depends on URL correctness, host availability, access rules, and network fetch timing.
Base64 embedding	You need to avoid a separate fetch, for example with a local development asset.	The image data becomes part of the HTML request, making that payload larger.

For a controlled diagnosis, compare a minimal document using one known absolute image URL with the same image embedded as Base64. If the embedded image appears and the remote one does not, investigate URL resolution, reachability, access controls, the server response, or timeout. This comparison is an inference from the documented fetch and embedding behavior, not a reported test result.

How can I see image-loading errors in DocRaptor?

Open the generated document’s log and inspect its Details view for conversion steps and resource problems. Look for clues such as a 404 response, DNS or connection failure, rejected access, a TLS/SSL problem, or a request that takes too long. DocRaptor documents that resource errors are ignored by default, so PDF generation can complete even if an image could not be loaded.

For systems where an incomplete PDF must be detected, set ignore_resource_errors to false. This makes documented resource failures fail the generation request instead of silently leaving you with an incomplete result. See Stop Ignoring Asset Loading Errors and the API reference.

Allow more time for a slow, reachable image

DocRaptor’s API documentation says external resource requests default to waiting up to 10 seconds and exposes an HTTP timeout setting from 1 to 60 seconds. Increase the timeout only when the asset is slow but reachable. More time cannot correct a bad URL, inaccessible host, rejected request, or missing base URL.

Could authentication or access controls block an image?

Check whether the image host expects credentials, cookies, an allowlisted network source, or another access condition. Do not assume credentials from your browser session are automatically sent to DocRaptor. The API reference documents prince_options[http_user] and prince_options[http_password] for HTTP Basic Authentication. If the host filters requests by IP or proxy rules, confirm that DocRaptor’s request path is allowed; consult the host and DocRaptor documentation rather than guessing which addresses to allow.

Do I need to enable JavaScript for images in a DocRaptor PDF?

Only if the document relies on JavaScript to create the image element, choose its URL, or finish an asynchronous load. JavaScript is disabled by default according to DocRaptor’s documentation. Enable the relevant engine and arrange for rendering to wait until the image-producing work is complete.

Do not enable JavaScript as a generic fix for a static broken URL: it will not make an inaccessible host reachable or supply a missing base. DocRaptor describes different roles for its standard and Prince JavaScript engines, and notes that Prince is not a browser and may not support every browser JavaScript behavior. See HTML to PDF JavaScript Execution.

Step-by-step diagnostic checklist

Inspect the exact input. Check the final HTML and CSS sent to DocRaptor, not only the browser source. Record each failing src or CSS url(...), including protocol-relative and root-relative paths.
Resolve each URL explicitly. Use a full https:// URL, or set prince_options[baseurl] or <base href>. Work out the final resolved address for root-relative paths.
Check from outside your development setup. Determine whether the image depends on localhost, a local filesystem path, private networking, VPN access, or a browser-only session.
Read DocRaptor’s document log. Use the Details view to identify which resource request failed and why.
Try one known image in a minimal document. Use an absolute URL and compare it with a Base64 version if useful. This narrows the cause to fetching versus other document behavior.
Check access and response conditions. Verify authentication, access filtering, host response, and TLS configuration for the asset URL.
Change timeouts only with evidence. If logs indicate a slow resource, consider a longer HTTP timeout within the documented 1–60-second range.
Check JavaScript only for generated or delayed content. Enable the needed engine and ensure the work finishes before capture.
Make failures observable. Consider ignore_resource_errors=false where missing assets must make the job fail and trigger monitoring.

Common errors and fixes

Symptom	Likely cause	What to do
Relative image path fails	No base URL, or a base pointing somewhere unexpected.	Use an absolute URL or set `prince_options[baseurl]`/`<base>`; verify the resolved path.
Browser image works, PDF image is absent	The renderer cannot access localhost, a private host, or a local file.	Use a publicly reachable asset, a development tunnel, or embedded Base64 data.
PDF job succeeds but image is missing	Resource errors are logged and ignored by default.	Inspect the document log; set `ignore_resource_errors` to `false` to surface failures.
Image URL returns an access or authentication error	The asset server requires credentials or filters requests.	Configure documented Basic Authentication options when applicable and review host access rules.
Image sometimes appears or times out	The host is slow or the request exceeds the configured wait.	Check logs and host response; increase timeout only if the host is reachable but slow.
Image inserted by page code is absent	JavaScript is disabled, unsupported for that behavior, or unfinished at render time.	Enable the appropriate JavaScript engine, wait for content readiness, or supply the image statically.
CSS background is absent while an `<img>` works	The CSS URL has a different relative base or is not present in the final submitted stylesheet.	Inspect the computed CSS source and give that URL an explicit resolution path too.

Performance, reliability, and cost considerations

Prefer stable, reachable assets. A remote image introduces a resource request whose outcome depends on the host and network. Embedding can remove that fetch dependency for selected assets, while increasing request size.
Use timeouts to handle latency, not correctness. A longer timeout may help a slow server but adds waiting when a resource is stalled; it does not fix addressing or access.
Fail visibly when completeness matters. Ignoring resource errors can yield a PDF with missing content. Turning that behavior off for resource errors lets your application treat incomplete generation as a failure and retry or alert according to its own policy.
Keep JavaScript work bounded. Static assets avoid script timing dependencies. If JavaScript is necessary, make readiness explicit and avoid relying on browser-only behavior.
Review sensitive debugging data. DocRaptor says a Help Request shares the input HTML, output document, and generation log with its support team. Review these materials for private customer or business data before submitting. See Requesting Help with your Document.

Or skip the browser setup

If the goal is a clean screenshot of a web page for a PDF workflow, report, or visual check, ScreenshotNeo is a website screenshot API and MCP server. It returns a PNG, JPEG, WebP, or PDF from one GET request. The direct rendering fixes above still apply to DocRaptor PDFs; ScreenshotNeo is an alternative when you need a website capture.

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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

See the ScreenshotNeo API documentation for request options and response details. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed; and an 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.

Frequently asked questions

Will sending HTML as document_content make its linked images available?

No. It avoids fetching the HTML document itself, but a separately linked image still needs to be reachable or embedded.

Does a successful PDF response mean all assets loaded?

No. DocRaptor documents that resource errors can be ignored by default. Check the document log, or configure resource errors to fail the job.

Should I raise the timeout for every missing image?

No. Use a longer timeout only when evidence points to a slow, reachable asset. A bad URL or inaccessible server needs a different fix.

Where can I find DocRaptor’s instructions?

Start with the official troubleshooting guide, then consult the linked API and topic-specific documentation for the setting involved.