How to Fix Puppeteer’s Cannot Read Properties of null textContent Error
Fix Puppeteer’s null textContent error by checking selectors, timing, frames, optional fields, and placeholder nodes with reliable code patterns.

Quick answer: Cannot read properties of null (reading 'textContent') means the value immediately before .textContent is null. In Puppeteer, that is usually the result of document.querySelector() or an element-level querySelector() that found no matching node. Fix it by inspecting the selector in the same page and frame, waiting only when the element is expected to appear later, and handling genuinely optional content explicitly.
The error is raised before any later fallback code can run. This pattern fails when no element matches:
const text = await page.evaluate(() => {
return document.querySelector('.target-selector').textContent;
});
Start with a null-safe query so you can distinguish “the field is absent” from “the field exists but is empty”:
const text = await page.evaluate(() => {
const element = document.querySelector('.target-selector');
return element ? element.textContent : null;
});
If the element should be inserted after navigation, wait for that selector before reading it:
await page.waitForSelector('.target-selector');
const text = await page.$eval('.target-selector', element => element.textContent);
Puppeteer’s Page.waitForSelector documentation states that the wait resolves when a matching element appears and throws when the timeout expires. A wait helps with delayed rendering; it cannot correct a misspelled, stale, or inapplicable selector.
What the error actually means
JavaScript evaluates a property access from left to right. In node.textContent, the runtime first evaluates node. If it is null, there is no object from which to read textContent, so execution stops with the TypeError. The textContent property itself is not the null value.

In Puppeteer, the null value commonly comes from one of these expressions:
document.querySelector(selector)returned no match.parent.querySelector(childSelector)found a parent but not the child.- A list contains a placeholder or template node whose markup differs from real records.
- The page has variant markup, so a class exists for some cards but not others.
- The script evaluated in the wrong frame or before client-side rendering finished.
A browser’s normal interactive state may differ from Puppeteer’s state because of authentication, cookies, viewport, user agent, navigation timing, consent dialogs, or bot checks. Always inspect the rendered DOM that Puppeteer actually received.
Step 1: Prove which query returned null
Break a chained expression into named values. This gives you a useful diagnostic instead of a line that hides the failing lookup:
const result = await page.evaluate(() => {
const card = document.querySelector('.card');
if (!card) {
return { foundCard: false, foundTitle: false, title: null };
}
const title = card.querySelector('.title');
return {
foundCard: true,
foundTitle: Boolean(title),
title: title ? title.textContent.trim() : null
};
});
console.log(result);
If foundCard is false, inspect the outer selector, page state, and frame. If the card exists but foundTitle is false, inspect the child selector and markup variants.
For a one-off check outside page evaluation, use Puppeteer’s locator methods and count matches:
const count = await page.$$eval('.card', nodes => nodes.length);
console.log('card count:', count);
const titles = await page.$$eval('.card .title', nodes =>
nodes.map(node => node.textContent.trim())
);
console.log(titles);
Save the HTML when the result is surprising. The exact DOM is more reliable than assumptions based on source templates:
const html = await page.content();
await require('node:fs').promises.writeFile('debug-page.html', html);
console.log(await page.url());
Step 2: Verify the selector against the rendered DOM
Check the selector in the page state where the error occurs. Confirm spelling, punctuation, capitalization, nesting, and whether the class is applied to the element you intend to read.
- Log
await page.url()immediately before evaluation. - Check that navigation completed to the expected URL.
- Inspect
await page.content()or a saved copy of the HTML. - Count matches with
$$eval. - Test the selector in the same frame, not only in a top-level browser tab.
Prefer stable attributes when the site provides them. A selector tied to a generated class or visual layout can become stale after a frontend deployment. If the site has a semantic attribute, use it:
const value = await page.$eval('[data-testid="product-title"]', node =>
node.textContent.trim()
);
Do not “fix” a selector by making it broad until it happens to match. A broad selector can silently extract navigation text, a hidden template, or an unrelated element.
Step 3: Wait for content that is rendered asynchronously
Navigation finishing does not guarantee that a client-rendered component has appeared. Wait for the element that proves the data is ready:
await page.goto('https://example.com/products', {
waitUntil: 'domcontentloaded'
});
await page.waitForSelector('.product-card .title', {
timeout: 15000,
visible: true
});
const titles = await page.$$eval('.product-card .title', nodes =>
nodes.map(node => node.textContent.trim())
);
Use a timeout that reflects the page’s normal load time. Increasing a timeout is useful only when the target legitimately appears later. If the selector never matches, a longer timeout delays the same failure.
Puppeteer also exposes waitForFunction for a readiness condition that is not represented by one selector:
await page.waitForFunction(() => {
return document.querySelectorAll('.product-card').length > 0;
}, { timeout: 15000 });
For a list, wait for a real record rather than a container that appears immediately:
await page.waitForSelector('.results .result-card');
Use the corresponding frame API when content is inside an iframe. The Frame.waitForSelector reference documents the same waiting behavior and notes that it works across navigations in that frame.
Step 4: Handle optional fields deliberately
Some records legitimately have no subtitle, price, badge, or description. A null check makes that data contract explicit:

const cards = await page.$$eval('.card', nodes =>
nodes.map(node => {
const title = node.querySelector('.title');
const summary = node.querySelector('.summary');
return {
title: title ? title.textContent.trim() : null,
summary: summary ? summary.textContent.trim() : null
};
})
);
Optional chaining is concise when undefined is an acceptable result:
const summary = node.querySelector('.summary')?.textContent?.trim();
Choose the output intentionally:
- Preserve
nullwhen missing means “not supplied.” - Use an empty string when downstream code requires text but absence is normal.
- Filter incomplete records only when incomplete records are not useful.
- Throw a descriptive error when the field is required by your data contract.
Do not use optional chaining to hide a broken selector. If every production card must have a title, fail with the card index and a short HTML excerpt:
const records = await page.$$eval('.card', nodes =>
nodes.map((node, index) => {
const title = node.querySelector('.title');
if (!title) {
throw new Error(`Missing .title in card ${index}`);
}
return title.textContent.trim();
})
);
Step 5: Inspect every list item, including placeholders
One successful match does not prove that all records share the same structure. Infinite-scroll pages, skeleton loaders, promoted cards, and template nodes can appear in the same collection. A reported Puppeteer case involved a first result that was a dummy node without the expected data; another involved class variants that omitted a child element.
Collect diagnostics for each item before deciding whether to filter or fail:
const diagnostics = await page.$$eval('.card', (nodes) =>
nodes.map((node, index) => {
const title = node.querySelector('.title');
return {
index,
className: node.className,
hasTitle: Boolean(title),
title: title ? title.textContent.trim() : null,
html: node.outerHTML.slice(0, 300)
};
})
);
console.table(diagnostics);
If placeholders are expected, select only completed records with a state attribute or a required child. If they are unexpected, keep the diagnostics and fix the upstream wait or selector.
Complete runnable Puppeteer example
This script demonstrates navigation, a targeted wait, null-safe extraction, list diagnostics, and a required-field check:
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();
try {
await page.goto('https://example.com/products', {
waitUntil: 'domcontentloaded',
timeout: 30000
});
await page.waitForSelector('.card', { timeout: 15000 });
const records = await page.$$eval('.card', nodes =>
nodes.map((node, index) => {
const title = node.querySelector('.title');
const summary = node.querySelector('.summary');
return {
index,
title: title ? title.textContent.trim() : null,
summary: summary ? summary.textContent.trim() : null,
className: node.className
};
})
);
const missingTitles = records.filter(record => !record.title);
if (missingTitles.length) {
throw new Error(
`Missing titles in cards: ${missingTitles.map(record => record.index).join(', ')}`
);
}
console.log(JSON.stringify(records, null, 2));
} finally {
await browser.close();
}
})();
Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
textContent is null immediately after goto |
Client-side rendering has not inserted the target. | Wait for the actual target selector or a readiness condition. |
waitForSelector times out |
Selector is wrong, page state is wrong, or content never loads. | Log the URL, save page.content(), verify authentication and inspect the rendered DOM. |
| Only some cards fail | Placeholder nodes or variant markup omit the child. | Inspect every item; filter known placeholders or handle the child as optional. |
| Selector works in DevTools but not Puppeteer | Different cookies, viewport, user agent, navigation state, or frame. | Reproduce the same state in Puppeteer and query the correct frame. |
| Parent query is null | The parent selector failed before the child lookup. | Check the parent first and include a diagnostic branch. |
| Text is empty rather than null | The element exists but contains no text, or text is rendered differently. | Inspect outerHTML; wait for content, not merely the container. |
| Intermittent failures | Race between navigation, data requests, and DOM updates. | Wait for a stable application signal and avoid arbitrary sleeps where possible. |
Timing, frames, and navigation edge cases
Do not confuse visibility with existence
waitForSelector can be configured to require visibility. A hidden element may exist as a template and still be the wrong match. Use visible: true when the user-facing element must be displayed, or query a state attribute that identifies completed content.
Wait after the navigation that changes the DOM
Clicking a filter, pagination control, or tab may trigger a new render without a full navigation. Await the click and then wait for a selector or state change that proves the new result arrived:
await Promise.all([
page.waitForSelector('.results[data-state="loaded"]'),
page.click('[data-page="2"]')
]);
Use the right iframe
Top-level page.$eval cannot query elements inside a child frame. Find the frame by URL or name, then query it:
const frame = page.frames().find(candidate =>
candidate.url().includes('/embedded-results')
);
if (!frame) throw new Error('Results frame not found');
await frame.waitForSelector('.result-title');
const title = await frame.$eval('.result-title', node => node.textContent.trim());
Account for consent and bot checks
A consent banner, challenge page, or blocked response can replace the expected application DOM. Check the final URL and a short body preview before extracting. If the page is a challenge rather than the target, changing the selector will not solve the underlying load problem.
Performance and reliability practices
- Wait for the narrowest meaningful readiness signal instead of sleeping for a fixed number of seconds.
- Use one page per concurrent task only when the host and your machine can handle the load; bound concurrency to avoid browser memory spikes.
- Reuse a browser process for batches, but create isolated pages and clear state between jobs.
- Record URL, selector, frame, elapsed time, and a DOM excerpt when extraction fails.
- Retry navigation failures with a limit and backoff, but do not retry a deterministic selector mismatch indefinitely.
- Pin selectors to stable attributes and keep selector tests alongside the scraper.
- Set explicit navigation and selector timeouts so a failed page does not hold a worker forever.
Retries improve reliability for transient network failures, not for a selector that never matches. Treat timeout rates, missing-field rates, and placeholder counts as separate signals so you can identify whether the problem is availability or page-shape drift.
Or skip the browser setup
If your goal is a clean screenshot rather than custom DOM extraction, ScreenshotNeo provides a one-request website screenshot API. It accepts options for full-page capture, element selectors, waits, custom CSS and JavaScript, cookies, headers, device presets, dark mode, PDFs, caching, bulk jobs, and more. Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status.
See the ScreenshotNeo API documentation for the complete option list. 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,
)
r.raise_for_status()
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 failed: ${res.status}`);
const data = Buffer.from(await res.arrayBuffer());
require('node:fs').writeFileSync('shot.webp', data);
ScreenshotNeo includes an MCP server with take_screenshot, get_page_info, and capture_pdf tools 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.
Cost and operational notes
Self-hosted Puppeteer uses your own compute, browser maintenance, bandwidth, and engineering time. ScreenshotNeo charges only for clean shots; failed loads, bot checks, blank pages, timeouts, and cache hits are free. Its plans are Free (1,000 shots/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, and every feature is available on every plan.
FAQ
Should I use optional chaining everywhere?
No. Use it when absence is valid. For required fields, throw a descriptive error so selector regressions are visible.
Does increasing the timeout fix this error?
Only when the element is expected to appear later. A wrong selector will still time out.
Why does the selector work in my normal browser?
Puppeteer may have different cookies, authentication, viewport, user agent, frame, or navigation state. Compare the rendered DOM and final URL.
Can I read text from an iframe with page.$eval?
No. Obtain the child frame and run waitForSelector and $eval on that frame.
Is an empty string the same as null?
No. null means no matching element was found; an empty string usually means the element exists but has no text.


