How to Fix PhantomJS Not Creating Screenshots
PhantomJS renders nothing, saves no file, or creates a blank image? Follow this diagnostic flow, working scripts, and fixes for loading, timing, paths, TLS, and clipping.

Direct answer: PhantomJS usually fails to create a screenshot because the script renders before page.open succeeds, exits before asynchronous work finishes, writes to an unwritable path, uses an unsupported filename extension, or captures an empty clipping rectangle. Render only after a successful load, wait for JavaScript content when necessary, use an explicit writable filename, and call phantom.exit() after page.render().
1. Start with the smallest known-good script
Save this as capture.js and run it with an explicit output path:

var page = require('webpage').create();
page.open('http://example.com', function (status) {
console.log('Status: ' + status);
if (status === 'success') {
page.render('/tmp/example.png');
console.log('Saved /tmp/example.png');
} else {
console.error('The page did not load, so no screenshot was rendered.');
}
phantom.exit();
});
Run:
phantomjs capture.js
ls -lh /tmp/example.png
page.render(filename) saves the current rendered page and infers the format from the extension. Use a recognized extension such as .png, .jpeg, .pdf, .bmp, or .ppm. GIF support depends on the Qt build.
2. Confirm PhantomJS and the file environment
Check which executable is running
which phantomjs
phantomjs --version
Multiple installations can cause you to edit one script while another binary runs it. Remove the ambiguity by using the full executable path in automation.
Check the output directory
pwd
mkdir -p /tmp/phantom-captures
touch /tmp/phantom-captures/write-test
rm /tmp/phantom-captures/write-test
Relative paths are resolved from the process working directory, which may differ under cron, CI, Docker, or a service account. Prefer an absolute path while diagnosing.
Check the extension
A filename without a supported extension can produce an error or an unexpected result. Start with capture.png; change format only after PNG works.
3. Do not render until the load callback succeeds
The callback status is the first useful diagnostic. A status other than success means the document did not finish loading successfully.
var page = require('webpage').create();
page.open('https://example.com', function (status) {
console.log('Status: ' + status);
if (status !== 'success') {
phantom.exit(1);
return;
}
page.render('/tmp/example.png');
phantom.exit();
});
Do not call phantom.exit() immediately after page.open(). That ends the process before the callback and render operation can complete.
4. Wait for pages populated by JavaScript
A successful navigation can still show an empty shell when the page fills itself through asynchronous JavaScript. Use a bounded delay, or poll for a selector that proves the content exists.
Simple delay
var page = require('webpage').create();
page.open('https://example.com/app', function (status) {
console.log('Status: ' + status);
if (status !== 'success') {
phantom.exit(1);
return;
}
window.setTimeout(function () {
page.render('/tmp/app.png');
phantom.exit();
}, 2000);
});
Wait for a selector with a timeout
var page = require('webpage').create();
var started = Date.now();
var timeoutMs = 10000;
function finish(code) {
phantom.exit(code || 0);
}
function check() {
var present = page.evaluate(function () {
return !!document.querySelector('#report');
});
if (present) {
page.render('/tmp/report.png');
finish(0);
return;
}
if (Date.now() - started >= timeoutMs) {
console.error('Timed out waiting for #report');
finish(1);
return;
}
window.setTimeout(check, 250);
}
page.open('https://example.com/report', function (status) {
console.log('Status: ' + status);
if (status !== 'success') {
finish(1);
return;
}
check();
});
Use a selector that is present only when the useful content is ready. A fixed delay is simpler but can be too short on a slow run and waste time on a fast one.
5. Add browser and network diagnostics
Capture page-level JavaScript errors
var page = require('webpage').create();
page.onError = function (msg, trace) {
console.error('Page error: ' + msg);
trace.forEach(function (item) {
console.error(' at ' + item.file + ':' + item.line);
});
};
page.open('https://example.com', function (status) {
console.log('Status: ' + status);
if (status === 'success') {
page.render('/tmp/diagnostic.png');
}
phantom.exit(status === 'success' ? 0 : 1);
});
Log requests and responses
var page = require('webpage').create();
page.onResourceRequested = function (request) {
console.log('Request: ' + request.method + ' ' + request.url);
};
page.onResourceReceived = function (response) {
if (response.stage === 'end') {
console.log('Response: ' + response.status + ' ' + response.url);
}
};
page.open('https://example.com', function (status) {
console.log('Status: ' + status);
if (status === 'success') {
page.render('/tmp/network.png');
}
phantom.exit(status === 'success' ? 0 : 1);
});
Missing JavaScript, CSS, image, font, or API requests often explain a blank or partially rendered image. The request log also reveals redirects and resources blocked by a proxy or certificate problem.
6. Fix viewport and clipping problems
viewportSize controls the browser viewport. clipRect limits the rectangle written to the image. An incorrect rectangle can create a tiny, blank, or apparently missing capture.
var page = require('webpage').create();
page.viewportSize = { width: 1440, height: 900 };
page.clipRect = { top: 0, left: 0, width: 1440, height: 900 };
page.open('https://example.com', function (status) {
if (status === 'success') {
page.render('/tmp/viewport.png');
}
phantom.exit(status === 'success' ? 0 : 1);
});
Remove clipRect temporarily when diagnosing. Once a full viewport works, add clipping with positive coordinates and dimensions that fit the page.
7. Investigate HTTPS, proxies, and old environments
- HTTPS fails while HTTP works: inspect the OpenSSL and SSL libraries used by the PhantomJS installation, then test with the exact URL and binary used in production.
- Requests are extremely slow on Windows: try the documented workaround
phantomjs --proxy-type=none capture.jswhen the default proxy behavior is involved. - Unexpected display-server errors: PhantomJS 1.5 and later are headless and do not require X11 or Xvfb. PhantomJS 1.4 and earlier did require an X server.
- Modern sites behave differently: PhantomJS development is suspended, and its QtWebKit engine predates many current browser features. A page can load in a current browser while scripts, TLS negotiation, or layout fail in PhantomJS.
8. A production-oriented PhantomJS script
This version combines status checks, error logging, a readiness selector, a timeout, viewport settings, and an absolute output path.
var system = require('system');
var webpage = require('webpage');
var url = system.args[1] || 'https://example.com';
var output = system.args[2] || '/tmp/phantom-shot.png';
var selector = system.args[3] || 'body';
var timeoutMs = 15000;
var page = webpage.create();
var started = Date.now();
var done = false;
page.viewportSize = { width: 1366, height: 768 };
page.onError = function (msg, trace) {
console.error('Page error: ' + msg);
trace.forEach(function (item) {
console.error(' at ' + item.file + ':' + item.line);
});
};
page.onResourceError = function (error) {
console.error('Resource error: ' + error.url + ' (' + error.errorString + ')');
};
function finish(code) {
if (done) return;
done = true;
phantom.exit(code || 0);
}
function waitForReady() {
var ready = page.evaluate(function (wanted) {
return !!document.querySelector(wanted);
}, selector);
if (ready) {
page.render(output);
console.log('Saved ' + output);
finish(0);
return;
}
if (Date.now() - started >= timeoutMs) {
console.error('Timed out waiting for selector: ' + selector);
finish(1);
return;
}
window.setTimeout(waitForReady, 250);
}
page.open(url, function (status) {
console.log('Status: ' + status);
if (status !== 'success') {
finish(1);
return;
}
waitForReady();
});
phantomjs capture.js https://example.com /tmp/example.png body
9. Troubleshooting checklist
| Symptom | Likely cause | Fix |
|---|---|---|
| No file is created | Process exits early, load failed, or path is unwritable | Log status, render inside the callback, call phantom.exit() afterward, and use an absolute writable path. |
| “page.render does nothing” | Render is called before navigation or after an unsuccessful status | Render only when status === 'success'. |
| Blank image | App content is asynchronous, scripts failed, or the clip rectangle is wrong | Wait for a readiness selector, enable page.onError, log resources, and remove clipRect while testing. |
| Partial page | Fixed delay is too short or lazy content has not arrived | Poll for the content that must appear and increase the timeout. |
| HTTPS page fails | Old TLS/OpenSSL support or certificate negotiation | Inspect the libraries linked to PhantomJS and compare with a current supported renderer. |
| Very slow Windows capture | Default proxy behavior | Try --proxy-type=none and inspect request logs. |
| Only a small corner is saved | Incorrect clipRect |
Set viewport and clip dimensions explicitly, or remove clipping. |
| Script hangs | Missing phantom.exit() or an unbounded wait loop |
Exit on success, failure, and timeout. |
10. Performance, reliability, and cost considerations
- Performance: Poll for a meaningful selector instead of sleeping for an unnecessarily large fixed delay. Avoid capturing more pixels than required, and keep network logging disabled outside diagnostics.
- Reliability: Set a hard timeout, return a nonzero process code on failure, preserve the status and error logs, and keep a minimized reproducible URL when reporting an issue.
- Compatibility: Treat PhantomJS as a legacy renderer. Compare JavaScript execution, wait controls, TLS support, viewport and clipping, diagnostics, deployment burden, and maintenance before moving a job to another service.
- Cost: A local PhantomJS process has no hosted screenshot charge, but you own runtime maintenance, failed jobs, browser compatibility work, and infrastructure. A managed API trades that operational work for request pricing; verify its billing rules and failure behavior before migrating.
11. Or skip the browser setup
If a legacy PhantomJS job still cannot produce a dependable file, ScreenshotNeo provides a managed screenshot API. It accepts one GET request and returns PNG, JPEG, WebP, or PDF. Cookie and consent banners, newsletter popups, and chat widgets are removed before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Responses identify the page verdict and billing result with X-Page-Verdict and X-Billed headers. ScreenshotNeo also provides an MCP server so Claude, Cursor, and other MCP clients can take screenshots, inspect pages, and capture PDFs.

See the ScreenshotNeo API documentation for all options.
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}`);
There are 1,000 screenshots per month on the free plan with no card required. Paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account.
12. Frequently asked questions
Does PhantomJS need Xvfb?
PhantomJS 1.5 and later are headless and do not require X11 or Xvfb. PhantomJS 1.4 and earlier required an X server.
Which image formats can page.render write?
PhantomJS documents PDF, PNG, JPEG, BMP, and PPM; GIF depends on the Qt build. The filename extension selects the format.
Why does a page that works in Chrome render blank?
PhantomJS uses an old QtWebKit engine. Modern JavaScript, TLS, or layout behavior may fail even when a current browser succeeds. Use page errors and resource logs to identify the failing part.
Should I keep increasing the delay?
No. A readiness selector with a maximum timeout is easier to reason about and avoids both premature captures and needless waiting.
How do I report a persistent PhantomJS failure?
Record the exact command, PhantomJS version, operating system, expected and actual behavior, logs, and a minimized reproducible page. That information makes the issue actionable.


