How to Find a Frame’s Parent in Puppeteer

Call frame.parentFrame() on the Puppeteer Frame whose parent you need. It returns another Frame, or null if the frame is the main frame or has been detached.

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.');
}

This is a synchronous lookup. The main frame is the page’s top-level document, so it has no parent. A child frame can itself contain child frames; parentFrame() moves up just one level.

1. Get a frame and inspect its parent

Here is a complete runnable example using Puppeteer. It opens a page, finds an iframe element, gets the corresponding Frame, and checks its parent. Install Puppeteer first with npm install puppeteer, then save this as parent-frame.js and run node parent-frame.js.

const puppeteer = require('puppeteer');

async function main() {
  const browser = await puppeteer.launch({ headless: true });

  try {
    const page = await browser.newPage();
    await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });

    const iframeElement = await page.$('iframe');
    if (!iframeElement) {
      console.log('No iframe element found on the page.');
      return;
    }

    const frame = await iframeElement.contentFrame();
    if (!frame) {
      console.log('The iframe is not attached to a frame.');
      return;
    }

    const parent = frame.parentFrame();
    if (parent) {
      console.log('Frame URL:', frame.url());
      console.log('Parent frame URL:', parent.url());
    } else {
      console.log('This is the main frame or the frame has been detached.');
    }
  } finally {
    await browser.close();
  }
}

main().catch(error => {
  console.error(error);
  process.exitCode = 1;
});

ElementHandle.contentFrame() can return null, so check its result before calling frame methods. Pages can also change between locating an iframe element and inspecting it; if the site replaces the iframe, reacquire the element and frame.

2. Understand the frame tree

Puppeteer models frames as a nestable tree, much like nested <iframe> elements. Start at page.mainFrame(); use frame.childFrames() to move down to direct children and frame.parentFrame() to move up one level.

function printFrameTree(frame, indent = '') {
  console.log(`${indent}${frame.url()}`);

  for (const child of frame.childFrames()) {
    printFrameTree(child, `${indent}  `);
  }
}

printFrameTree(page.mainFrame());

This traversal reports the current frame tree. If you already have the child frame, you do not need to search the tree just to find its immediate parent. If you need the whole ancestry path, repeatedly call parentFrame() until it returns null:

function getAncestors(frame) {
  const ancestors = [];
  let current = frame.parentFrame();

  while (current) {
    ancestors.push(current);
    current = current.parentFrame();
  }

  return ancestors;
}

const ancestors = getAncestors(frame);
console.log(ancestors.map(item => item.url()));

The returned array starts with the immediate parent and continues toward the main frame. A null at the end is expected for the main frame; do not treat it as an exception.

3. Handle detached frames and page changes

A frame may be removed or replaced as a page runs. The documented method returns null for a detached frame as well as for the main frame. Consequently, a null result alone does not tell you which case occurred.

If you only need a safe parent lookup, check for null and continue appropriately.
If you need to distinguish the main frame from a detached frame, compare the candidate with page.mainFrame() while the page is in a state you control; page changes can still race with subsequent operations.
If the iframe element was replaced, locate it again and call contentFrame() again rather than relying on an old handle.
When waiting for a dynamically inserted iframe, wait for the iframe element or the site-specific condition that creates it before getting its content frame.

const mainFrame = page.mainFrame();
const parent = frame.parentFrame();

if (parent) {
  console.log('Parent:', parent.url());
} else if (frame === mainFrame) {
  console.log('The frame is the page main frame.');
} else {
  console.log('The frame has no parent; it may have been detached.');
}

The equality check helps classify the current main frame, but it is not a substitute for handling page lifecycle changes. If navigation or DOM replacement is happening concurrently, reacquire the relevant frame after the change.

4. Common errors and fixes

Symptom	Likely cause	Fix
`parentFrame is not a function`	The value is not a Puppeteer `Frame`, or a different object such as an iframe element handle was passed.	Get the frame with `elementHandle.contentFrame()` or from the page’s frame tree, then check that it is non-null.
The parent is `null`	The frame is the main frame or has been detached.	Handle both documented cases. If the frame should be an iframe, reacquire it after the page has finished the relevant DOM update.
`contentFrame()` returns `null`	The element handle does not currently correspond to an attached frame.	Wait for the iframe to appear or become attached, then query it again.
No iframe element is found	The page has not inserted it yet, the selector is wrong, or the content is not embedded as an iframe.	Check the selector and timing. Inspect `page.frames()` if you want the browser’s current frame list.
Unexpected frame URL	The frame navigated after it was first discovered, or a different nested frame was selected.	Log the selected frame and its parent URLs immediately before using them; refresh the frame reference after navigation or replacement.

5. Performance, reliability, and cost

parentFrame() is a direct frame relationship lookup and does not require evaluating page JavaScript or making another network request. For a single parent lookup, use it directly. For broader inspection, traverse from page.mainFrame() through childFrames(); avoid repeatedly walking the entire tree when the needed frame is already known.

The main reliability concern is lifecycle timing: pages can add, remove, or navigate frames while automation is running. Resolve the frame near the point of use, check nullable results, and make waits depend on the page condition your workflow actually needs. Puppeteer browser automation also has the operational cost of running and maintaining a browser process; for a one-off screenshot, a screenshot API can avoid that browser setup.

6. Or skip the browser setup

If your goal is a screenshot rather than frame-tree inspection, ScreenshotNeo provides a one-call website screenshot API. Its API accepts a URL and returns an image or PDF. See the ScreenshotNeo API documentation.

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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month.

7. FAQ

Is `parentFrame()` asynchronous?

No. It returns a Frame or null directly, so there is no need to await it.

Does it return the top-level page when called on a child frame?

It returns the immediate parent only. Call it repeatedly to walk farther up the frame tree.

What should I use to get a frame’s children?

Use frame.childFrames() for its direct children, or recursively traverse from page.mainFrame() to inspect the current tree.

Where is the official API behavior documented?

The Puppeteer Frame.parentFrame reference documents the nullable return. The Frame class reference covers the related frame-tree methods.