How to Fix DocRaptor CSS Not Loading from a URL
Fix missing DocRaptor styles by checking URL resolution, server access, resource logs, and network settings. Includes API examples and a diagnostic checklist.
If DocRaptor generates a PDF without the expected styles, first verify that the stylesheet has a resolvable URL and that DocRaptor’s servers can reach it. Use an absolute https:// URL, set a correct prince_options[baseurl], or add a <base> element to the document head. Then inspect the conversion log: resource download errors are ignored by default, so a completed PDF does not prove that its CSS loaded.
This guide covers the likely causes, runnable requests, configuration checks, and a way to make failed resource retrieval visible.
1. Check how the stylesheet URL is resolved
A relative stylesheet path needs a base location. For example, href="styles/print.css" does not say which host or directory contains the file. Protocol-relative URLs such as //example.com/styles.css and root-relative paths such as /styles.css can also fail when the renderer has no valid base URL. DocRaptor documents this situation as a “File System Access is Not Allowed” error. DocRaptor: File System Access is Not Allowed
Option A: use an absolute URL
<link rel="stylesheet" href="https://example.com/assets/print.css">This is the simplest diagnostic. Copy the resulting URL and check that it points to the intended stylesheet, including the scheme, host, path, and filename.
Option B: set prince_options[baseurl]
If your HTML intentionally uses relative paths, provide the location against which they should resolve. Set the base to match the document’s asset layout. For example, if the HTML refers to assets/print.css and that path is relative to https://example.com/reports/, the base should be that directory. Check DocRaptor’s API reference for the accepted request format for your client and API version.
prince_options[baseurl]=https://example.com/reports/Do not guess the base: resolve the relative stylesheet reference yourself and confirm that the resulting full URL is the one you expect.
Option C: add a <base> element
If you control the HTML head, set a document-level base:
<head>
<base href="https://example.com/reports/">
<link rel="stylesheet" href="assets/print.css">
</head>A base element affects relative URLs in the document, not just the stylesheet. Review relative links and other assets when adding or changing it.
2. Confirm DocRaptor’s servers can access the stylesheet
A stylesheet that loads in your local browser may still be unavailable to DocRaptor. The URL must be reachable from DocRaptor’s rendering servers. A private-network hostname, localhost, or a development server accessible only on your machine cannot be fetched directly from those servers.
For local development, you can submit HTML as document_content instead of asking DocRaptor to fetch the HTML from a URL. That does not make linked CSS accessible by itself: external stylesheets still need to be reachable. For a self-contained document, put the CSS in a <style> element. If you need to test a local server with external assets, DocRaptor’s guidance also mentions using a temporary tunnel that makes it reachable over the internet. See DocRaptor’s local development guidance.
3. Embed the CSS when a separate request is unnecessary
DocRaptor supports linked stylesheets, <style> blocks, and inline styles. Embedded CSS avoids a separate stylesheet fetch, along with URL-resolution, access, authorization, TLS, and request-timeout problems for that file. DocRaptor describes embedded styles as slightly faster because it does not need to fetch the CSS file. Keep a linked stylesheet when sharing or maintaining it separately is useful; embed it when reducing external dependencies is more important.
<head>
<style>
@page { size: A4; margin: 18mm; }
body { font-family: sans-serif; color: #222; }
h1 { break-after: avoid; }
</style>
</head>This only removes the external request for the CSS you embedded. Any other linked fonts, images, scripts, or stylesheets remain separate resources and must still be available if the document uses them.
See DocRaptor’s CSS guidance for its CSS support details.
4. Inspect the document log instead of relying on a successful response
DocRaptor ignores external resource download errors by default. As a result, conversion can complete while a stylesheet or image is missing. Inspect the document log for the resource URL and its failure reason. The API option ignore_resource_errors can be set to false so covered resource failures cause generation to fail. This is useful when an incomplete PDF should be treated as an error by your application or monitoring.
Failing generation on resource errors makes missing dependencies easier to detect, but it also means any covered resource problem can fail the whole document. DocRaptor lists HTTP 400 and 500 responses, DNS failures, unknown MIME types, connection timeouts, SSL problems, and rejected connections among the possible resource errors. Check the API reference for the exact parameter syntax in your integration.
Python request example
This example sends HTML content and asks resource errors to fail generation. Replace the placeholder with your API key and adjust the HTML and options to match the document. The documented API uses the prince_options[ignore_resource_errors] parameter name.
import requests
api_key = "YOUR_API_KEY"
html = """<!doctype html>
<html>
<head>
<link rel=\"stylesheet\" href=\"https://example.com/assets/print.css\">
</head>
<body><h1>Report</h1></body>
</html>"""
response = requests.post(
"https://docraptor.com/docs",
auth=(api_key, ""),
data={
"doc[document_content]": html,
"doc[name]": "report.pdf",
"doc[document_type]": "pdf",
"prince_options[ignore_resource_errors]": "false",
"prince_options[baseurl]": "https://example.com/",
},
timeout=90,
)
response.raise_for_status()
with open("report.pdf", "wb") as output:
output.write(response.content)DocRaptor’s request fields and authentication conventions can vary by client library; use its official API documentation to adapt the form field names if you use a wrapper or a different API version. The key diagnostic settings are the base URL when paths are relative and failing on resource errors when you want missing resources surfaced.
5. Review network and authentication options
Several secondary settings can explain a failed fetch, but they address specific conditions rather than all missing-CSS problems.
| Setting or condition | When to check it | What it can and cannot do |
|---|---|---|
prince_options[http_timeout] |
The stylesheet host responds slowly. | DocRaptor documents a range of 1–60 seconds and a default of up to 10 seconds for an external resource request. A longer timeout can help with slow retrieval; it will not fix a malformed URL or an unreachable private host. |
prince_options[http_user] and prince_options[http_password] |
The resource requires HTTP authentication supported by these options. | Provide the credentials required to retrieve the resource. Confirm that the host’s access method is compatible. |
prince_options[no_network] |
You are reviewing whether network retrieval has been disabled. | This option disables network downloads. If it is enabled, an external stylesheet cannot be fetched. |
| SSL verification settings | The log reports a certificate or SSL issue. | Fix the certificate or server configuration where possible. DocRaptor labels disabling SSL verification as not recommended; do not use it as a routine workaround. |
These settings are documented in the DocRaptor API reference. Check your actual outgoing request: an option in application configuration has no effect if the client does not serialize it into the API request.
6. Troubleshoot by symptom
| Symptom or log clue | Likely cause | Fix |
|---|---|---|
| “File System Access is Not Allowed” | A relative or protocol-relative resource path has no valid base. | Use an absolute URL, set prince_options[baseurl], or add a suitable <base> element. |
| The PDF succeeds but appears unstyled | External resource errors are ignored by default, or the CSS URL returned an error. | Inspect the document log and resource response. Temporarily set ignore_resource_errors to false to make covered failures visible. |
| The link works in your browser but not in conversion | The renderer cannot access a private host, local machine, or development server. | Use a publicly reachable resource, embed the CSS, or make the development resource reachable using an appropriate temporary tunnel. |
| DNS, connection, or rejected-connection error | The host cannot be resolved or reached from the renderer’s network. | Check the hostname, DNS, public accessibility, and server access rules. A longer timeout only helps if the host is slow rather than unreachable. |
| HTTP 400 or 500, or unexpected response type | The server is returning an error or not serving CSS as expected. | Request the exact stylesheet URL and inspect its status and response headers. Fix the server response and confirm that the URL points to the CSS file. |
| Timeout | The resource host is taking longer than the configured fetch window. | Improve response time or increase prince_options[http_timeout] within the documented 1–60 second range. Avoid raising it without checking total document latency. |
| SSL error | The stylesheet host has a certificate or TLS problem. | Correct the host’s certificate chain or TLS configuration. Treat disabling verification as a last resort, consistent with DocRaptor’s warning. |
| CSS still seems incomplete after loading | The stylesheet may itself reference other resources or contain rules that do not produce the expected print layout. | Check the log for additional resource failures, inspect CSS print rules and referenced fonts or images, and reduce the document to a small reproducible example. |
7. A practical diagnostic sequence
- Record the exact failing CSS URL. Inspect the submitted HTML and resolve relative references against the effective base.
- Choose one URL strategy. Make the link absolute, set the request’s
baseurl, or define a document<base>. Confirm the resulting full URL. - Check reachability from outside your environment. Verify that the resource is not limited to localhost, a private network, a VPN, or an authenticated browser session.
- Read the document log. Look for the exact URL, status or transport error, and any secondary assets referenced by the stylesheet.
- Make resource errors fail during diagnosis. Set
ignore_resource_errorstofalseif you want a failed fetch to fail conversion, then decide whether that policy suits production. - Remove the fetch if practical. Embed manageable CSS in a
<style>block and compare the output. - Review timeout, credentials, and network options. Change only the option that matches the observed error.
- Escalate with evidence. If the problem remains, use the log’s Details view and DocRaptor’s Help Request workflow. Include the stylesheet URL, whether you submit a document URL or content, the base URL, relevant request settings, and the log error. DocRaptor says Help Requests are normally available for documents created within the previous seven days. See DocRaptor’s Help Request guidance.
Or skip the browser setup
If you need a screenshot of the page or a visual asset for a report, [ScreenshotNeo](https://screenshotneo.com) provides a website screenshot API and MCP server. It does not replace DocRaptor’s HTML-to-PDF workflow; use it when an image capture is what you need.
One GET request returns an image or PDF. See the ScreenshotNeo API documentation for request options.
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}`);- Cookie banners, newsletter popups, and chat widgets are removed before the shot.
- Bot checks, blank pages, and failed loads are never billed.
- An MCP server lets AI agents take screenshots.
- 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000.
Sign up free for ScreenshotNeo: get 1,000 screenshots a month with no card.
Performance, reliability, and cost considerations
- Performance: Each external stylesheet introduces a retrieval dependency. Embedding CSS removes that fetch; DocRaptor describes embedded styles as slightly faster. Increasing the resource timeout can lengthen a failed or slow conversion, so use it only when the log points to slow retrieval.
- Reliability: Use stable, reachable asset URLs and make resource failures visible in development or monitoring when incomplete output is unacceptable. A successful PDF response alone is not a resource health check.
- Cost: The dossier provides no DocRaptor pricing details, so cost impact cannot be quantified here. Operationally, diagnose repeated failed conversions and avoid retrying unchanged requests. ScreenshotNeo’s listed plans are 1,000 free monthly shots, then $5/3,000, $15/15,000, $39/60,000, $99/250,000, and $249/1,000,000; yearly billing gives two months free.
Frequently asked questions
Does sending HTML as document_content make linked CSS available?
No. It avoids DocRaptor fetching the HTML document itself, but linked stylesheets still need to be reachable. Embed the CSS if you need a self-contained document.
Should I always set ignore_resource_errors to false?
Use it when a missing resource should make the document fail and become visible to your application. If optional assets are allowed to fail, inspect logs and choose a policy that matches your document requirements.
Will increasing the timeout fix a missing stylesheet?
Only when the cause is a slow response. It cannot fix an incorrect URL, missing base, private host, disabled network access, or authentication mismatch.
Where can I get help for a specific failed conversion?
Review the document log’s Details view and use DocRaptor’s Help Request workflow when available. Include the exact resource URL and observed error so the fetch context is clear.
