Start by checking which PhantomJS binary is running, then separate page errors from stalled requests and script-lifecycle waits. This sequence is for diagnosing an existing legacy installation: PhantomJS is backed by QtWebKit, and its official site says development is suspended until further notice. The available documentation does not establish compatibility with any particular current website.
1. Confirm the executable and version
Run phantomjs --version in the same environment that launches the screenshot script. The CLI documentation identifies 2.1.1 as its documented latest release and says --debug=true prints additional warnings and debug messages. A machine can have multiple installations, so check the resolved path and the command used by a package script or service if the reported version is unexpected.
phantomjs --version
which phantomjsOn Windows, use where phantomjs in place of which. Compare the resolved path with the binary your script or job runner invokes. Documentation: PhantomJS troubleshooting and PhantomJS command-line options.
2. Find out whether the page throws an error
Attach page.onError before opening the page. Print the exception and its stack trace; otherwise, a page-side JavaScript failure may look like a screenshot that simply never finishes. Capture console messages as well if the script currently discards them.
#1 Best Overall
page.onError = function (msg, trace) {
console.log("PAGE ERROR: " + msg);
trace.forEach(function (frame) {
console.log(" " + frame.file + ":" + frame.line);
});
};
page.onConsoleMessage = function (msg) {
console.log("PAGE CONSOLE: " + msg);
};These callbacks reveal page diagnostics; they do not themselves impose a deadline on the whole script. The PhantomJS troubleshooting documentation describes page error handling and remote debugging: troubleshooting guide.
3. Identify a stalled network request
Log resource requests to find the last URL requested before progress appears to stop. Include a timestamp so repeated runs can distinguish a slow request from a request that never completes.
page.onResourceRequested = function (request) {
console.log(new Date().toISOString() + " REQUEST " + request.url);
};If plain HTTP works but HTTPS fails or stalls, inspect the SSL libraries available to the specific PhantomJS binary. The legacy documentation also notes that a default proxy on Windows can add substantial latency; if that applies, test with --proxy-type=none and compare. This is a diagnostic test, not a general recommendation to bypass a required proxy. See PhantomJS troubleshooting.
Rank #2
4. Set a resource timeout before opening the page
page.settings.resourceTimeout is in milliseconds. It limits an individual resource request and triggers page.onResourceTimeout. Set it before the first page.open; changing it afterward does not affect that call.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallpage.settings.resourceTimeout = 15000;
page.onResourceTimeout = function (request) {
console.log("RESOURCE TIMEOUT: " + request.url);
};
page.open(targetUrl, function (status) {
console.log("OPEN STATUS: " + status);
// Continue with the page-specific readiness check and capture.
});Choose a limit appropriate to the page and environment; 15 seconds above is an example, not a PhantomJS default or a universal threshold. A resource timeout is not a whole-program timeout: script callbacks, polling loops, or page JavaScript can still wait indefinitely. Documentation: WebPage settings and WebPage API.
5. Trace capture, readiness, and process exit
Check each stage explicitly: did the page.open callback run, did the script reach page.render, and did it call phantom.exit() afterward? The official screen-capture example renders from the open callback and then exits. If the page updates asynchronously, an open callback alone may be too early; define a readiness condition specific to the target page and pair it with a separate overall watchdog.
var page = require("webpage").create();
var system = require("system");
var targetUrl = system.args[1];
page.onError = function (msg, trace) {
console.log("PAGE ERROR: " + msg);
trace.forEach(function (frame) {
console.log(" " + frame.file + ":" + frame.line);
});
};
page.onResourceRequested = function (request) {
console.log(new Date().toISOString() + " REQUEST " + request.url);
};
page.onResourceTimeout = function (request) {
console.log("RESOURCE TIMEOUT: " + request.url);
};
page.settings.resourceTimeout = 15000;
page.open(targetUrl, function (status) {
console.log("OPEN STATUS: " + status);
if (status !== "success") {
phantom.exit(1);
return;
}
// Replace this delay with a target-specific readiness check when needed.
window.setTimeout(function () {
page.render("shot.png");
phantom.exit(0);
}, 1000);
});
// Overall watchdog: resourceTimeout alone cannot stop all script-level waits.
var watchdog = window.setTimeout(function () {
console.log("OVERALL WATCHDOG: capture deadline reached");
phantom.exit(2);
}, 30000);This is a diagnostic skeleton, not a universal dynamic-page recipe. The one-second delay is illustrative; use a condition that reflects the page’s actual content or state. Ensure the watchdog is cleared after successful capture if your script structure could otherwise leave it active. The official example demonstrates the open-render-exit sequence but does not prescribe one readiness signal for every site: PhantomJS screen capture.
6. Check X-server assumptions only when the symptom points there
If the error is specifically about an X server or display, first check the version. PhantomJS 1.4 and earlier require an X server; version 1.5 and later are pure headless and do not require X11 or Xvfb, according to the FAQ. For an SELinux-specific block, the troubleshooting page flags SELinux as a possible issue, but the documented material does not establish a generally valid policy fix.
See the PhantomJS FAQ and troubleshooting guide.
7. Use the inspector when logs are not enough
If available in your installation, --remote-debugger-port=9000 can expose the documented WebKit inspector workflow for examining the script and page. Treat that endpoint as a local diagnostic interface: restrict binding and access to what is appropriate for the host, and do not expose it publicly without an explicit security design. The option is documented in the PhantomJS CLI reference.
Or skip the browser setup
For new screenshot work, ScreenshotNeo offers a screenshot API and MCP server. A single GET request can return a screenshot or PDF; this cURL example saves a WebP image. See the API documentation for parameters.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp- Cookie and consent banners are accepted before capture, and known consent platforms, newsletter popups, and chat widgets are removed; each step can be turned off.
- Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and billing status.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdftools for AI agents and MCP clients. - The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Yearly billing gives two months free, and every feature is on every plan.
Sign up for 1,000 free screenshots a month, with no card required.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Frequently Asked Questions
What is the documented latest PhantomJS release?
The PhantomJS CLI reference lists 2.1.1 as the documented latest release; check the binary installed in your own environment with phantomjs --version.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Does PhantomJS 1.5 or later require Xvfb?
According to the PhantomJS FAQ, 1.5 and later are pure headless and do not require X11 or Xvfb; 1.4 and earlier require an X server.
Does a resource timeout stop every kind of hang?
No. It applies to an individual resource request. A script callback, polling loop, or page-side wait needs its own bounded deadline.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
