How to Fix PhantomJS Null Is Not an Object Errors
Fix PhantomJS “null is not an object” errors by checking selectors, load status, timing, frames, and page context with defensive code.

Short answer: PhantomJS reports null is not an object when an expression returns null and the next operation dereferences it. The usual example is document.querySelector('#map').getBoundingClientRect(): if #map is not in the current DOM yet, querySelector() returns null, so calling getBoundingClientRect() fails. MDN documents that querySelector() returns null when no element matches. MDN querySelector reference
Fix it by checking the page-load status, validating the selector in the live page, waiting for a deterministic readiness condition on dynamic pages, and keeping DOM access inside page.evaluate(). Also check that you are on the expected URL and frame.
What the error means
JavaScript evaluates a chained expression from left to right. In this code:
var box = page.evaluate(function () {
return document.querySelector('#map').getBoundingClientRect();
});
the selector lookup happens first. If there is no matching element, the result is null. The subsequent .getBoundingClientRect() access then raises the TypeError. The same problem occurs with .textContent, .click(), .value, or any other property or method accessed on the missing value.
Reliable fix workflow
- Check
page.open()status. Continue only when the callback receivessuccess. PhantomJS documents that the callback receivessuccessorfailafter loading. PhantomJSpage.openAPI - Query and guard in the page context. Return plain JSON data such as
found,readyState, and text instead of returning a DOM node. - Verify the selector. Check spelling, punctuation, attributes, and whitespace against the rendered markup.
- Wait for the actual condition. A successful network load does not mean client-side rendering has finished. Poll for the required element or state.
- Check navigation and frames. Confirm
page.urland query the correct document when content is inside an iframe. - Capture diagnostics. Log the URL, status, selector, ready state, and a short HTML excerpt. Forward page console messages with
page.onConsoleMessage.

A complete defensive PhantomJS script
Save this as check-element.js and run phantomjs check-element.js https://example.com '#map'. It checks loading, polls for the selector, and returns useful diagnostics.
var page = require('webpage').create();
var system = require('system');
if (system.args.length < 3) {
console.log('Usage: phantomjs check-element.js URL SELECTOR');
phantom.exit(64);
}
var url = system.args[1];
var selector = system.args[2];
var maxWaitMs = 10000;
var pollMs = 250;
var startedAt;
page.onConsoleMessage = function (message) {
console.log('PAGE: ' + message);
};
function diagnostics(reason) {
var data = page.evaluate(function () {
return {
url: location.href,
readyState: document.readyState,
html: document.documentElement ? document.documentElement.outerHTML.slice(0, 1000) : ''
};
});
console.log(JSON.stringify({
reason: reason,
requestedUrl: url,
currentUrl: page.url,
selector: selector,
page: data
}, null, 2));
}
function pollForElement() {
var result = page.evaluate(function (cssSelector) {
var element = document.querySelector(cssSelector);
if (!element) {
return {
found: false,
readyState: document.readyState
};
}
return {
found: true,
readyState: document.readyState,
text: element.textContent || '',
rect: (function () {
var r = element.getBoundingClientRect();
return { left: r.left, top: r.top, width: r.width, height: r.height };
}())
};
}, selector);
if (result.found) {
console.log(JSON.stringify(result, null, 2));
phantom.exit(0);
return;
}
if (Date.now() - startedAt >= maxWaitMs) {
diagnostics('selector-not-found-before-timeout');
phantom.exit(2);
return;
}
window.setTimeout(pollForElement, pollMs);
}
page.open(url, function (status) {
if (status !== 'success') {
diagnostics('page-open-failed');
phantom.exit(1);
return;
}
startedAt = Date.now();
pollForElement();
});
page.evaluate() is sandboxed: page code cannot access variables in the PhantomJS script, and closures, DOM nodes, and other complex objects should not cross the boundary. Pass simple arguments and return JSON-serializable values. See the PhantomJS evaluate API and PhantomJS Quick Start.
Validate selectors before dereferencing
A selector can fail because an ID or class is misspelled, an attribute is wrong, or a space changes the meaning. For example, img [alt="PhantomJS"] searches for a descendant of an img element, while img[alt="PhantomJS"] tests the attribute on the image itself.
var check = page.evaluate(function (cssSelector) {
var element = document.querySelector(cssSelector);
return {
found: !!element,
selector: cssSelector,
readyState: document.readyState,
matches: document.querySelectorAll(cssSelector).length
};
}, '#map');
console.log(JSON.stringify(check, null, 2));
When the count is zero, inspect page.content or the rendered page source. Remember that a selector operates on the current live DOM, not necessarily the original HTML response.
Wait for dynamic content without arbitrary delays
Single-page applications and widgets often create elements after the initial load callback. Prefer polling for the element or a state marker. A fixed sleep can be too short on a slow run and unnecessarily slow on a fast one.
function waitForSelector(cssSelector, timeoutMs, intervalMs, done) {
var started = Date.now();
function check() {
var state = page.evaluate(function (selector) {
var node = document.querySelector(selector);
return {
found: !!node,
readyState: document.readyState
};
}, cssSelector);
if (state.found) {
done(null, state);
return;
}
if (Date.now() - started >= timeoutMs) {
done(new Error('Timed out waiting for ' + cssSelector));
return;
}
window.setTimeout(check, intervalMs);
}
check();
}
waitForSelector('#map', 15000, 200, function (error, state) {
if (error) {
console.log(error.message);
phantom.exit(2);
return;
}
console.log(JSON.stringify(state));
phantom.exit(0);
});
For delayed work that must run inside the page, PhantomJS also provides evaluateAsync(function, delayMillis, ...). See the official evaluateAsync API. Keep the completion condition explicit so a page that never renders the element cannot hang indefinitely.
Check navigation, frames, and page identity
Navigation changed the document
Redirects, login flows, and client-side routing can replace the DOM after the first response. Log both the requested URL and page.url, then query after the final navigation.
page.open(url, function (status) {
console.log(JSON.stringify({
status: status,
requestedUrl: url,
currentUrl: page.url
}));
if (status !== 'success') {
phantom.exit(1);
return;
}
// Query only after confirming the document is the one you expect.
});
The element is inside an iframe
Selectors run against the current document. An element inside an iframe is not found by querying the parent document. Identify the frame, switch to its context using the frame APIs available in your PhantomJS version, and then run the query there. If the frame loads asynchronously, apply the same readiness polling inside that frame.
The page is not the page you think it is
Authentication failures, bot checks, redirects, and error pages can produce a valid success load with completely different markup. Include a short page.content excerpt and the final URL in failure logs.
Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
document.querySelector(...).property throws |
No matching element | Store the result, test it for null, then access the property. |
| Works manually, fails in PhantomJS | Element is rendered later or browser-dependent markup differs | Poll for a readiness condition and inspect the rendered HTML. |
Selector always returns null |
Typo, incorrect punctuation, or unintended whitespace | Test the selector with querySelectorAll and compare it with live markup. |
page.open callback is fail |
Network, DNS, TLS, or server failure | Stop DOM work, log the URL and status, and retry or fix connectivity. |
| Selector exists in source but not in evaluation | Wrong frame or navigation replaced the document | Confirm page.url and query the correct frame after navigation. |
| Returning a DOM node gives unusable data | evaluate cannot serialize DOM nodes across its sandbox boundary |
Return text, numbers, booleans, or plain objects instead. |
| Page-side logs are missing | Evaluate console output is not shown automatically | Set page.onConsoleMessage and prefix messages with PAGE:. |
| Intermittent timeout | Readiness condition is too strict, or the page has variable latency | Use a bounded timeout, log state on expiry, and wait for the smallest reliable condition. |
Safer null-handling patterns
// Guard before calling a method
var text = page.evaluate(function () {
var node = document.querySelector('#status');
return node ? (node.textContent || '') : null;
});
// Return a structured result for callers
var result = page.evaluate(function () {
var node = document.querySelector('#status');
if (!node) {
return { found: false, value: null };
}
return { found: true, value: node.textContent || '' };
});
// Avoid assuming a nested property exists
var href = page.evaluate(function () {
var link = document.querySelector('a.download');
return link && link.href ? link.href : null;
});
Do not hide the problem by catching every exception and continuing. A missing required element should produce a clear, actionable failure with the selector and page state.
Performance, reliability, and cost considerations
- Poll at a moderate interval such as 200–500 ms instead of running a tight loop that consumes CPU.
- Use the narrowest readiness condition that proves the next operation is safe. Waiting for an entire page when one component is required increases latency.
- Set a maximum timeout and return diagnostics on expiry so failed jobs do not remain stuck.
- Cache or reuse static page setup where appropriate, but re-check selectors after every navigation.
- When capturing many pages, record status, final URL, selector, and failure reason per page rather than treating the batch as one success or failure.
- PhantomJS is an older headless browser. If a target depends on modern browser features, reproduce the issue in a maintained browser automation stack or use a screenshot service that handles browser setup.
Or skip the browser setup
ScreenshotNeo provides a website screenshot API and MCP server. One request returns a PNG, JPEG, WebP, or PDF, so you do not need to install PhantomJS or maintain page-load and selector-wait code for a screenshot job. The ScreenshotNeo API documentation lists the 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}`);
ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Create a free ScreenshotNeo account and start with 1,000 screenshots per month without a card.
FAQ
Does null is not an object always mean the selector is wrong?
No. The selector may be correct but evaluated before asynchronous rendering, in another frame, or after navigation changed the document.
Should I add a five-second sleep?
Use a condition-based poll instead. A fixed delay has no guarantee of being sufficient and adds latency when the element is already ready.
Can I return an element from page.evaluate()?
Return simple serialized data instead. DOM nodes and closures do not cross the PhantomJS evaluation boundary reliably.
What should I log when the error is intermittent?
Log the requested URL, page.url, load status, selector, document.readyState, timeout elapsed, and a short rendered HTML excerpt.
What if the page requires a modern browser?
PhantomJS may not execute the page as a current browser would. Use a maintained browser automation tool or a screenshot API that manages the browser environment.


