Call frame.parentFrame() on the Puppeteer Frame object. It returns the parent frame, or null when the frame is the main frame or has been detached.
Get a frame’s parent
Use parentFrame() on the frame you already have:
const parent = frame.parentFrame();
if (parent) {
console.log('Parent frame URL:', parent.url());
} else {
console.log('This is the main frame or the frame has been detached.');
}The return type is Frame | null. Check for null before calling methods such as url() on the result. The Puppeteer Frame.parentFrame() reference documents this behavior in Puppeteer 25.0.1.
As an Amazon Associate I earn from qualifying purchases.
Understand the result
- A nested frame:
parentFrame()returns its immediate parent, one level up the frame tree. - The main frame: it has no parent, so the method returns
null. - A detached frame: the method also returns
null. A frame reference may no longer be attached when the page’s frame structure changes, so do not assume a parent always exists.
Inspect the whole frame tree
For broader inspection, start at page.mainFrame() and walk downward with childFrames(). These methods complement the upward lookup from parentFrame():
Free tools Windows power users keep installed
One-click scans. No signup required.
function printFrameTree(frame, indent = '') {
console.log(indent + frame.url());
for (const child of frame.childFrames()) {
printFrameTree(child, indent + ' ');
}
}
printFrameTree(page.mainFrame());This recursively prints each frame’s URL, indenting children beneath their parent. The Puppeteer Frame class reference describes the frame tree and these companion methods; that reference displays version 25.12.0.
#1 Best Overall
Common problems
- Calling a method on
null: check the result before accessing the parent’s URL or other properties. The selected frame may be the main frame, or may have detached. - Expecting the top-level frame:
parentFrame()moves up only one level. To inspect the tree from its root, usepage.mainFrame()and traverse withchildFrames(). - Assuming a compatibility range: the cited API pages document the behavior for the versions shown above, but do not establish compatibility history across all Puppeteer releases. Check the reference matching the version installed in your project.
Or skip the browser setup
If your goal is a clean website screenshot rather than inspecting Puppeteer’s frame hierarchy, ScreenshotNeo returns a screenshot or PDF from one GET request. Its API and MCP server can help developers and AI agents capture pages without configuring a browser themselves.
For example, save a WebP screenshot of a page with cURL:
Quick Recap
Rank #3
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. Before capture, it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for ScreenshotNeo’s free plan.
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.
