How to Fix PhantomJS Screenshots That Do Not Render Web Fonts
Find out why PhantomJS screenshots fall back to system fonts, how to inspect font requests and wait before rendering, and when to change renderers.

PhantomJS screenshots can show fallback fonts even when the page itself opened successfully. The usual causes are a screenshot taken before the font finished loading, a failed or timed-out font request, an incorrect @font-face declaration, or a font/runtime compatibility issue. Log the font request and page errors first; then add a bounded readiness wait that your PhantomJS build supports. PhantomJS uses an older QtWebKit runtime, so do not assume that modern document.fonts.ready exists.
The reliable debugging sequence is: reproduce with the same PhantomJS executable and host as production, inspect the requested font URL and response, verify the face CSS, wait before rendering, and compare the output. If this is a new or actively maintained workflow, account for the fact that PhantomJS development is suspended. PhantomJS project site · ScreenshotNeo.
1. Determine whether the font request happened
A successful page.open() callback means the navigation completed according to PhantomJS; it is not proof that every stylesheet, image, script, and remote font has finished loading. Start by recording resource requests, responses, and timeouts. PhantomJS documents resource timeout configuration and request diagnostics in its WebPage settings API and troubleshooting guide.

Check these four things
- Was a font URL requested? If not, inspect whether the stylesheet loaded, whether its media condition applies, and whether the captured element uses the expected family and weight.
- Did it return successfully? A missing response, error, or timeout suggests a network, TLS, access-control, server, or URL problem. Check the exact URL from the log.
- Does the face match the requested style? Confirm the
font-family,font-weight,font-style, and source format in@font-face. The page may request a bold or italic face that was never declared. - Did the page script fail? A JavaScript exception may prevent a stylesheet or class change that triggers the intended font. Log page errors separately from resource failures.
Do not infer font success from a visually complete page or an HTTP 200 on the HTML document. Inspect the font resource itself.
2. Add resource and JavaScript diagnostics
This PhantomJS script logs requests and responses, records resource timeouts and page errors, sets a finite resource timeout, then renders after a bounded delay. Save it as capture.js and run it with phantomjs capture.js https://example.com output.png. Replace the URL and output path as needed.
var page = require('webpage').create();
var system = require('system');
var address = system.args[1] || 'https://example.com';
var output = system.args[2] || 'capture.png';
var resources = {};
page.settings.resourceTimeout = 15000;
page.onResourceRequested = function (request) {
resources[request.id] = request.url;
console.log('REQUEST ' + request.id + ' ' + request.url);
};
page.onResourceReceived = function (response) {
if (response.stage === 'end') {
console.log('RESPONSE ' + response.id + ' ' + response.status + ' ' + response.url);
}
};
page.onResourceTimeout = function (request) {
console.log('TIMEOUT ' + request.id + ' ' + request.url);
};
page.onResourceError = function (resourceError) {
console.log('RESOURCE ERROR ' + resourceError.url + ' ' + resourceError.errorString);
};
page.onError = function (message, trace) {
console.log('PAGE ERROR ' + message);
trace.forEach(function (frame) {
console.log(' at ' + frame.file + ':' + frame.line);
});
};
page.open(address, function (status) {
console.log('OPEN ' + status + ' ' + address);
if (status !== 'success') {
phantom.exit(1);
return;
}
// A bounded fallback wait, not proof that the font is ready.
window.setTimeout(function () {
page.render(output);
console.log('SAVED ' + output);
phantom.exit(0);
}, 3000);
});
The resources map is optional; remove it if you do not need to correlate IDs. The essential clues are the request URL, completion status, timeout/error callbacks, and page-side exceptions. If the request succeeds but the screenshot still uses a fallback, move on to readiness, CSS matching, font format support, and host configuration.
3. Wait for the font before rendering
A fixed delay can help when the request is simply late, but it is a compromise: short waits may still capture too early, while long waits waste time on every capture. Prefer a page-side readiness signal if the page exposes one. Otherwise use a bounded delay and retain resource diagnostics so a timeout does not look like a successful font load.
Modern browsers expose document.fonts.ready, a promise that resolves when used fonts have loaded and layout operations have completed. See MDN’s Document.fonts reference. PhantomJS uses an old QtWebKit build; support can vary, so feature-check in the exact executable before relying on this interface.
page.open(address, function (status) {
if (status !== 'success') {
phantom.exit(1);
return;
}
var hasFontReady = page.evaluate(function () {
return !!(document.fonts && document.fonts.ready);
});
if (hasFontReady) {
page.evaluate(function () {
return document.fonts.ready.then(function () { return true; });
}, function () {
page.render('capture.png');
phantom.exit(0);
});
} else {
window.setTimeout(function () {
page.render('capture.png');
phantom.exit(0);
}, 3000);
}
});
PhantomJS bridge behavior for returning promises is not uniform across old builds, so treat this sketch as a capability-dependent pattern, not a universal drop-in. For maximum compatibility, let the page signal readiness by setting a known flag, poll that flag from PhantomJS with a deadline, and render only when it becomes true. If the page cannot expose a signal, choose a bounded delay based on observed resource timing and report when the deadline expires.
A bounded polling pattern for page-owned readiness
If your application can set window.__captureReady = true after it has applied the desired font and settled layout, PhantomJS can poll it without relying on a modern FontFaceSet API. The polling deadline avoids hanging forever on pages that never become ready.
var deadline = Date.now() + 10000;
var poll = setInterval(function () {
var ready = page.evaluate(function () { return window.__captureReady === true; });
if (ready || Date.now() >= deadline) {
clearInterval(poll);
if (!ready) console.log('READINESS TIMEOUT; rendering with diagnostics');
page.render('capture.png');
phantom.exit(ready ? 0 : 2);
}
}, 100);
Run the polling code after a successful page.open(). The page must own and set the readiness flag; otherwise it will only time out. A timeout screenshot may still be useful for diagnosis, but callers should distinguish it from a capture where the intended font was confirmed.
4. Verify the CSS face and font file
Check the stylesheet actually used by the captured page. A typical declaration looks like this:
@font-face {
font-family: "Product Sans";
src: url("/assets/product-regular.woff2") format("woff2");
font-style: normal;
font-weight: 400;
font-display: swap;
}
body { font-family: "Product Sans", Arial, sans-serif; }
Use a URL that resolves from the page’s origin, and verify it directly in the same network environment. Check redirects, authentication requirements, certificate/TLS behavior, and whether the server permits the browser runtime to fetch the file. If the CSS declares only weight 400 but the captured content requests 700, the renderer may synthesize a weight or select a fallback. Test the exact content and CSS state represented in the screenshot.
Do not assume a format supported by a current browser is supported by the particular PhantomJS/QtWebKit build. The dossier does not establish a complete format compatibility matrix. If the request succeeds but rendering fails, reduce the case to one face and one element, then compare supported formats in the deployed build.
5. Check the PhantomJS executable and host fonts
Reproduce in the same operating system and container used for production. Confirm which binary runs with phantomjs --version and check the actual executable path when multiple versions are installed. PhantomJS’s troubleshooting guide specifically calls out version confusion as a source of misleading results.

If the remote font request succeeds but text still falls back, check whether the rendering environment depends on locally installed fonts and whether the intended face is discoverable by that host. One PhantomJS GitHub issue includes a Linux report where installing TTF files under /usr/share/fonts/truetype and running fc-cache -fv allowed that reporter’s PDF workflow to use the face. Another commenter reported that upgrading dependencies fixed their case. These are environment-specific reports, not universal remedies; see the issue discussion.
# Linux example from the reported environment; adapt to your image and package policy.
fc-cache -fv
phantomjs --version
Installing a host font cannot fix a font URL that was never requested, a blocked response, or a CSS family mismatch. Diagnose those first. For repeatable CI, bake the required font files and fontconfig setup into the same image used for capture, then verify the result after rebuilding the image.
6. Choose a remedy that matches the cause
| Observed symptom | Likely cause | Next action |
|---|---|---|
| No font request in logs | Stylesheet, selector, family, or weight did not trigger it | Inspect loaded CSS and the captured element’s computed style |
| Request times out or errors | Network, TLS, URL, access, or server issue | Test the logged font URL from the same host and fix reachability |
| Request succeeds; fallback remains | Capture timing, face mismatch, unsupported format, or host dependency | Wait for readiness, check face descriptors, then reproduce on the production runtime |
| Works locally but not in CI | Different binary, dependencies, network, or installed fonts | Pin and inspect the executable and make the container environment reproducible |
| Intermittent fallback | Race between font loading/layout and render | Use a readiness signal with a deadline and log whether it was reached |
PhantomJS development is suspended according to the project site. For an existing workflow, a bounded wait and better diagnostics may be enough. For a new or actively maintained workflow, compare maintained browser renderers for the exact font formats and CSS you need, explicit font/resource waiting, host font setup, reproducible deployment, and debugging hooks. The dossier does not verify a specific replacement or its feature matrix, so validate candidates against a representative page before migrating.
7. Or skip the browser setup
If your goal is a clean website screenshot rather than maintaining a PhantomJS runtime, ScreenshotNeo provides a single GET endpoint. The request below captures a URL as WebP; see the ScreenshotNeo API documentation for its request options.
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}`);
- Cookie and consent banners, newsletter popups, and chat widgets are removed before capture; each step can be turned off.
- Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Responses identify the page verdict and billing status in headers.
- An MCP server gives AI agents tools for screenshots, page information, and PDF capture.
- The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Every feature is on every plan.
Sign up free for 1,000 screenshots a month, no card required.
8. Performance, reliability, and cost considerations
For self-hosted PhantomJS, total capture time includes navigation, page resources, any readiness wait, and rendering. A fixed delay adds that full delay to every capture, even when the font is already cached. A readiness signal can reduce unnecessary waiting, but it needs a timeout and useful logs so a permanently blocked request does not hang a worker. Resource timeouts should be selected for the pages and network your job actually handles; setting them too low creates false failures, while unbounded requests can occupy workers.
Reliability depends on reproducing the runtime: pin the PhantomJS version, dependencies, operating system image, and required host fonts. Capture request IDs, URLs, response status, resource errors, page errors, and whether readiness was reached. Keep a known page fixture with the same font path and face descriptors to separate renderer problems from site changes.
The dossier provides no PhantomJS benchmark or service cost figures. Estimate self-hosted cost from worker capacity, execution time, infrastructure, and maintenance effort rather than assuming a particular throughput. For ScreenshotNeo, the listed tiers are Free: 1,000/month; Starter: $5 for 3,000; Growth: $15 for 15,000; Pro: $39 for 60,000; Scale: $99 for 250,000; and Business: $249 for 1,000,000. Yearly billing gives two months free. Only clean shots are billed, and the response headers report billing status.
9. Troubleshooting checklist
- The page opened, but the font is missing: inspect the font URL in resource logs; page navigation success is not font success.
- No request appears: check stylesheet load, media rules, selector state, family name, and requested weight/style.
- A resource timeout appears: test network access to that exact URL from the production host; inspect TLS, redirects, credentials, and server availability.
document.fontsis undefined: this can be expected in an old PhantomJS runtime. Feature-check and use a page-owned readiness flag or bounded wait.- The request succeeds but fallback persists: confirm the CSS face matches, investigate format/runtime support, and reproduce on the same host.
- It works on a developer machine only: compare
phantomjs --version, executable path, dependencies, network, and installed fonts. - The wait never finishes: add a deadline, log readiness timeout, and render or fail explicitly according to your job’s needs.
- Only PDF output fails: compare PDF with image output and check the host-font behavior; the cited Linux report was specifically about PDF and is not a general rule.
FAQ
Does page.open() wait for web fonts?
Do not rely on it as proof that every remote font has loaded and been applied. Log the font resource and wait for a supported readiness signal.
Can I always use document.fonts.ready in PhantomJS?
No. It is a modern browser API, and support in the old PhantomJS runtime must be checked in the exact build.
Will installing a TTF file fix every missing web font?
No. It helped one reported Linux environment, but cannot correct missing requests, URL failures, or CSS face mismatches.
Should I migrate from PhantomJS?
PhantomJS development is suspended. For new or actively maintained work, evaluate a maintained renderer with a representative page and deployment image.


