Why PhantomJS Renders Websites as Black Squares and How to Fix It
PhantomJS black squares usually mean missing fonts, unsupported graphics, or an unclear background. Identify the cause and choose a reliable fix.

PhantomJS black squares are a symptom, not one specific bug. If boxes replace letters, investigate missing fonts and font discovery. If a large region or canvas is black, check whether the page depends on WebGL, CSS 3-D, video, or another feature PhantomJS cannot reliably render. If the whole image looks unexpectedly dark or empty, make the page background explicit and check for failed page or resource loads.
PhantomJS uses QtWebKit, so modern pages can exceed its rendering capabilities. Its feature documentation says WebGL requires an OpenGL-capable system and advises against relying on it; CSS 3-D, video, and audio also have documented limitations. Installing a font can fix missing glyphs, but it cannot add WebGL support. PhantomJS supported web standards
This guide walks through diagnosis, a runnable PhantomJS debugging script, font and background fixes, and when to move the capture to a maintained browser engine. For a managed screenshot API alternative, see ScreenshotNeo.
1. Classify what the black squares replace
Start with the artifact itself. Save the image and inspect whether the black areas are individual character-sized boxes, a full canvas or graphic region, or a broad area that ought to be a page background. This simple distinction avoids changing unrelated settings.

| What you see | Likely cause | First check |
|---|---|---|
| Squares in place of Arabic, Chinese, Japanese, or other characters | Required glyphs are absent or unavailable to the PhantomJS process | Check installed fonts, fontconfig discovery, and the CSS font stack |
| One large black rectangle where a chart, animation, or canvas should appear | Unsupported WebGL, CSS 3-D, rendering path, or script failure | Try a minimal 2-D fallback and inspect page errors |
| Unexpected transparent-looking or dark background | The page did not set a background, or transparency is being interpreted differently by the viewer | Set an explicit background before rendering |
| Part of the page is blank, stale, or incomplete | Resources did not load, the page rendered before it was ready, or an exception stopped drawing | Log page errors, resource requests, and load status |
Reproduce the problem with the same URL, viewport, PhantomJS executable, operating system, and output format. Then create a minimal test page with plain text on a solid background. If the minimal page also has glyph boxes, focus on fonts. If only the original page fails, inspect its graphics features and dependencies.
2. Confirm which PhantomJS binary and version run
On systems with multiple installations, the executable found in a shell can differ from the one used by a service, container, CI job, or wrapper script. Record the path and version alongside the operating system and capture parameters.
command -v phantomjs
phantomjs --version
If your job invokes PhantomJS through a wrapper or application, log the resolved executable path from that process too. Verify its environment and font access under the same user account that performs the capture. The official troubleshooting guide warns that multiple installations can lead to invoking the wrong binary and recommends checking the version. PhantomJS troubleshooting
PhantomJS is a legacy renderer. Updating to the latest version available to your environment may resolve a known defect, but it does not guarantee compatibility with modern page features. Its documentation recommends feature detection and extensive testing rather than assuming every supported feature works perfectly. Feature support notes
3. Use a diagnostic script before changing configuration
Capture JavaScript exceptions, request and response events, and the final load status. This makes it easier to tell a font or script loading problem from an unsupported rendering feature. Save the following as diagnose.js:
var page = require('webpage').create();
var system = require('system');
var address = system.args[1];
if (!address) {
console.log('Usage: phantomjs diagnose.js https://example.com');
phantom.exit(2);
}
page.viewportSize = { width: 1365, height: 900 };
page.onError = function (message, trace) {
console.log('[page error] ' + message);
trace.forEach(function (frame) {
console.log(' ' + frame.file + ':' + frame.line +
(frame.function ? ' in ' + frame.function : ''));
});
};
page.onResourceRequested = function (request, networkRequest) {
console.log('[request] ' + request.url);
};
page.onResourceReceived = function (response) {
if (response.stage === 'end') {
console.log('[response] ' + response.status + ' ' + response.url);
}
};
page.onResourceError = function (error) {
console.log('[resource error] ' + error.errorCode + ' ' +
error.errorString + ' ' + error.url);
};
page.onLoadFinished = function (status) {
console.log('[load finished] ' + status);
page.evaluate(function () {
// Remove this override if transparency is the intended output.
document.documentElement.style.backgroundColor = '#ffffff';
if (document.body) document.body.style.backgroundColor = '#ffffff';
});
page.render('diagnostic.png');
phantom.exit(status === 'success' ? 0 : 1);
};
page.open(address, function (status) {
if (status !== 'success') {
console.log('[open failed] ' + status);
phantom.exit(1);
}
});
Run it with the same PhantomJS binary used by your application:
phantomjs diagnose.js https://example.com
Review the output for failed stylesheet, font, image, and script requests, HTTP errors, or page exceptions. A successful top-level load does not prove every resource succeeded. Conversely, a request can fail without being the cause of the black region; compare failures to the broken content before treating them as causal. The PhantomJS guide documents page error and resource hooks as useful troubleshooting tools. Resource request handler
4. Fix black-square text by providing the right fonts
When boxes replace particular characters, the renderer usually lacks glyph coverage for those characters, or the font files are not discoverable by the process. A CSS stack can name several fonts, but fallback only works if suitable fonts are installed and visible on the capture host.
- Identify the affected writing system and inspect the page’s computed font family. Confirm that the intended font actually contains the missing glyphs.
- Install a font package with the needed language coverage on the machine or image that runs PhantomJS. Package names vary by distribution and version; use that system’s package search rather than copying a package command blindly.
- Check that the font files are readable by the PhantomJS user and that fontconfig can see them. On systems with fontconfig, inspect available fonts with
fc-listand refresh its cache withfc-cache -f -vafter adding fonts. - Restart a long-running worker if it may have cached font information, then capture the minimal text page again before retrying the full site.
- Keep required font files and installation steps in the deployment image or provisioning configuration so a clean host and later deployments behave consistently.
A reported CentOS 6.5/PhantomJS 1.9.7 Arabic-glyph case was fixed by installing the Arabic language support group with yum groupinstall 'Arabic Support'. That is evidence for that older CentOS environment, not a universal fix or command for other Linux distributions. Platform-specific Arabic font report
Do not assume a general-purpose Latin font covers every language. If characters still appear as boxes, verify the actual fallback font and glyph coverage rather than repeatedly reinstalling the same package. Also check that the page is not requesting a remote web font that fails due to network, TLS, access-control, or URL problems.
5. Fix background ambiguity explicitly
PhantomJS rendering does not automatically make a page background opaque. Its FAQ says the page remains transparent when the page does not set a background. If the output format or viewer displays transparency as black, the screenshot can look like a rendering failure even though the page rendered as intended. PhantomJS FAQ
Set a background in the page before capturing. For a one-off diagnosis, the earlier script applies white after page load. If you own the page, defining the background in its CSS is generally more reliable:
html, body {
background-color: #fff;
}
For a page you cannot change, evaluate a small override after load and before render(). This addresses transparency only. It does not repair missing glyphs, failed requests, or unsupported canvas features.
6. Check WebGL, CSS 3-D, and other unsupported content
PhantomJS uses QtWebKit. The project’s standards page explains that WebGL needs an OpenGL-capable system and that Mesa emulation may overcome the limitation with degraded performance. It also says not to rely on CSS 3-D, video, or audio support. A command-line switch should not be presented as a dependable way to make these capabilities work. Documented PhantomJS limitations
For an affected chart or animation, create a minimal page that draws the same content, then test whether a static image or 2-D rendering path works. If it does, offer that fallback to the renderer. If the site fundamentally requires WebGL or modern browser behavior, move the job to a maintained browser engine that supports the required features. Decide by capability and repeatability, not by whether one screenshot happens to look correct.
For a migration, compare feature coverage (including WebGL and CSS 3-D), output determinism, language and font support, maintenance and security posture, deployment complexity, and performance. A font installation is appropriate when glyph coverage is the cause; changing the browser is appropriate when the page needs capabilities PhantomJS does not provide.
7. Debug a minimal reproduction with remote inspection
When logs do not explain the result, reduce the page to the smallest case that still fails. PhantomJS supports WebKit remote debugging. For example, start a script with a debugging port:
phantomjs --remote-debugger-port=9000 diagnose.js https://example.com
Use the local inspector workflow described in the troubleshooting documentation to inspect both the PhantomJS script and target page. A debugger; statement can pause script execution; page.evaluateAsync() can pause inside page code. Keep the debug port restricted to a trusted local environment, and close the process when finished. Remote debugging instructions
Test one variable at a time: first plain text, then the relevant font, then the canvas or CSS effect, and finally the full page. Record the viewport, output type, host image, executable path, and version. This creates a useful reproduction if the issue is a renderer defect rather than deployment configuration.
8. Or skip the browser setup
If your goal is a clean screenshot rather than maintaining a local PhantomJS environment, ScreenshotNeo provides a website screenshot API and MCP server for developers. Its capture call is one GET request; see the ScreenshotNeo API documentation.

cURL
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webp
Python
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)
Node.js
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);
ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients. The Free plan includes 1,000 screenshots a month without a card; paid plans start at $5 for 3,000 shots, and every feature is on every plan. Sign up free for 1,000 screenshots a month, no card required.
9. Reliability, performance, and cost considerations
PhantomJS performance can change with the page’s scripts, resource count, graphics path, font configuration, and host. Mesa emulation is specifically documented as a possible WebGL workaround with degraded performance. Measure representative pages in the deployment environment if throughput matters; there is no universal benchmark for black-square fixes.
For repeatable output, pin the browser binary and operating system image, install fonts explicitly, use a fixed viewport, and wait for the content your job needs. Log errors and resource outcomes. Avoid treating a successful process exit as proof that every visual element rendered correctly. Add a visual review or image comparison for important output, with tolerances for dynamic content.
Cost includes more than CPU time: maintaining an old renderer, installing language fonts, reproducing failures, and migrating scripts can dominate a small capture job. A local fix is sensible when the issue is a font or transparent background and the legacy engine remains sufficient. Migration or a screenshot service may be simpler when modern graphics or frequent renderer maintenance are central to the workload. Do not infer a cost or performance advantage without measuring the actual deployment and capture volume.
10. Troubleshooting checklist
| Symptom | Likely cause | Action |
|---|---|---|
| Only some languages show boxes | Missing font coverage or font discovery failure | Install the language fonts, verify with fontconfig, refresh cache, and rerun as the capture user |
| A chart or canvas is a black rectangle | WebGL/CSS 3-D limitation or page exception | Check logs; reproduce minimally; use a 2-D/static fallback or migrate browser engine |
| Whole page has a dark or unexpected background | Transparent page background | Set an explicit CSS background before rendering |
| Fonts or images intermittently disappear | Failed or delayed resource, network or TLS issue | Log resource failures and responses; check connectivity and SSL/OpenSSL configuration |
| CLI and application results differ | Different binary, version, user, environment, or installed fonts | Log executable path and version from the application process; compare its environment |
| Fix works locally but not in CI | Different host image, font packages, cache, or user permissions | Reproduce using the CI image and account; encode font setup in the image |
| Changing fonts does not fix a whole canvas | Cause is likely not glyph coverage | Test feature support and page errors instead of adding unrelated fonts |
FAQ
Can a PhantomJS flag reliably enable WebGL?
No reliable flag is documented as a general fix. The project describes the OpenGL requirement and Mesa possibility, while warning about performance and advising users not to rely on unsupported features.
Why do glyph boxes appear only on the server?
The server may have fewer language fonts than a desktop, or its font cache and permissions may differ. Compare the installed and discoverable fonts under the actual capture account.
Will a white background fix black squares?
It can clarify transparent-background output. It will not supply missing glyphs or make unsupported graphics render.
Should I keep fixing PhantomJS or migrate?
Keep it when the problem is isolated to fonts or background and its legacy feature set meets the job. Migrate when the page depends on modern graphics or behavior that the renderer cannot reliably support.


