Check the read-only frame.detached property. It returns true when that Puppeteer Frame has been detached and false otherwise.
if (frame.detached) {
console.log('The frame has been detached');
}The older frame.isDetached() method is obsolete; use the property instead. See the Puppeteer Frame API.
Check a frame’s current state
If you already have a Frame reference, read frame.detached at the point you need to know its state:
if (frame.detached) {
console.log('The frame has been detached');
} else {
console.log('The frame is still attached');
}In TypeScript, the same check applies:
if (frame.detached) {
// Do not use this Frame for further frame work.
}The property is a boolean snapshot, not a guarantee that the frame will remain attached during a later operation.
#1 Best Overall
React when a frame is detached
Use the page’s framedetached event when your code needs to respond to a detach transition. Register the listener before the action that might remove or replace the iframe:
page.on('framedetached', detachedFrame => {
console.log('Frame detached:', detachedFrame.url());
});
// Perform the action that may remove or replace a frame here.Puppeteer dispatches frame attachment, navigation, and detachment lifecycle events on the parent page. The PageEvent API documents that framedetached carries the detached Frame. A listener added after a transition cannot observe that past event.
Confirm whether a saved frame is still in the page
page.frames() returns the frames currently attached to the page. To corroborate the property check against that inventory:
const stillInPage = page.frames().includes(frame);
if (frame.detached || !stillInPage) {
console.log('Do not use this frame reference');
}The direct state check is frame.detached; membership in the current frame list is a useful cross-check when you need to compare a saved reference with the page’s current frames. See the Page.frames API.
Free tools Windows power users keep installed
One-click scans. No signup required.
Checks that can mislead
parentFrame() === null
This is not a definitive detach test. Puppeteer documents that parentFrame() returns null for both detached frames and the main frame. Use frame.detached to distinguish the detached state.
Disposed element or JavaScript handles
A stale element or JavaScript handle does not by itself prove that the frame is detached. Puppeteer automatically disposes JSHandles when their associated frame navigates away or their parent execution context is destroyed. That concerns execution-context lifetime; check frame.detached for the frame’s detach state. See the JSHandle API.
Rank #4
Handle operations that race with page changes
A frame may detach after you check frame.detached but before a subsequent frame operation runs. Check close to the operation and handle errors from work that races with navigation or removal; a prior false value does not reserve the frame for later use.
if (!frame.detached) {
try {
const title = await frame.title();
console.log(title);
} catch (error) {
// The page or frame may have changed while the operation was running.
console.error('Could not read the frame:', error);
}
}Which check should you use?
| Approach | Use it for | Limitation |
|---|---|---|
frame.detached |
Checking a known frame reference now | Point-in-time state; the page can change afterward. |
page.on('framedetached', handler) |
Responding to a detach transition | Register before the transition to observe it. |
Common problems and fixes
- The method is missing or marked obsolete: Replace
frame.isDetached()withframe.detached. parentFrame()returnsnull, but the frame may be the main frame: Do not treat that result as proof of detachment; inspectframe.detached.- The event handler did not run: Register
framedetachedbefore the action that removes or replaces the iframe. - The frame operation fails after a false check: The frame may have detached in the interval. Check closer to use and catch errors from operations that can race with page changes.
- A handle is disposed: Handle disposal can follow navigation or destruction of its execution context; it is not a substitute for checking the frame property.
Version note
The current Frame API reference identifies Puppeteer 25.12.0 and documents the read-only detached property. Its older-method reference identifies 25.8.0 and marks isDetached() obsolete. Check the API reference for the Puppeteer version installed in your project if you are maintaining version-sensitive code.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteOr skip the browser setup
For website screenshots rather than frame-lifecycle checks, ScreenshotNeo can return an image or PDF from one GET request. Cookie banners are accepted and removed before the shot, along with supported newsletter popups and chat widgets. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status. It also has an MCP server for AI agents, with screenshot, page-info, and PDF tools.
Example request (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.webpThe free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.
Quick Recap
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.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →
