microsoft/playwright · error · Error

Selecting the nth frame is not allowed while piercing frames

Error message

Selecting the nth frame is not allowed while piercing frames.

What it means

Error "Selecting the nth frame is not allowed while piercing frames." thrown in microsoft/playwright.

Source

Thrown at packages/playwright-core/src/client/locator.ts:509

  getByTitle(text: string | RegExp, options?: { exact?: boolean }): Locator {
    return this.locator(getByTitleSelector(text, options));
  }

  getByRole(role: string, options: ByRoleOptions = {}): Locator {
    return this.locator(getByRoleSelector(role, options));
  }

  owner() {
    return new Locator(this._frame, this._frameSelector);
  }

  frameLocator(selector: string): FrameLocator {
    return new FrameLocator(this._frame, this._childSelector(selector));
  }

  private _nthSelector(nth: string): string {
    if (selectorPiercesFrames(this._frameSelector))
      throw new Error(`Selecting the nth frame is not allowed while piercing frames.`);
    if (this._frameSelector === kNoPierceFramesSelector)
      throw new Error(`Selecting the nth frame is not allowed on the root frame locator.`);
    return this._frameSelector + ` >> nth=${nth}`;
  }

  first(): FrameLocator {
    return new FrameLocator(this._frame, this._nthSelector('0'));
  }

  last(): FrameLocator {
    return new FrameLocator(this._frame, this._nthSelector('-1'));
  }

  nth(index: number): FrameLocator {
    return new FrameLocator(this._frame, this._nthSelector(String(index)));
  }
}

View on GitHub (pinned to c8fc3bf8d3)

When it happens

Trigger: Thrown at packages/playwright-core/src/client/locator.ts:509 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of microsoft/playwright@c8fc3bf8d3 (2026-08-12). Data as JSON: /api/errors/3468a6148c52617d. Report an issue: GitHub.