microsoft/playwright · error · Error

Locator must belong to the main frame of this page

Error message

Locator must belong to the main frame of this page

What it means

Error "Locator must belong to the main frame of this page" thrown in microsoft/playwright.

Source

Thrown at packages/playwright-core/src/client/page.ts:429

    return await this._mainFrame.content();
  }

  async setContent(html: string, options?: channels.FrameSetContentOptions & TimeoutOptions): Promise<void> {
    return await this._mainFrame.setContent(html, options);
  }

  async goto(url: string, options?: channels.FrameGotoOptions & TimeoutOptions): Promise<Response | null> {
    return await this._mainFrame.goto(url, options);
  }

  async reload(options: channels.PageReloadOptions & TimeoutOptions = {}): Promise<Response | null> {
    const waitUntil = verifyLoadState('waitUntil', options.waitUntil === undefined ? 'load' : options.waitUntil);
    return Response.fromNullable((await this._channel.reload({ ...options, waitUntil }, this._timeoutSettings.navigationTimeout(options))).response);
  }

  async addLocatorHandler(locator: Locator, handler: (locator: Locator) => any, options: { times?: number, noWaitAfter?: boolean } = {}): Promise<void> {
    if (locator._frame !== this._mainFrame)
      throw new Error(`Locator must belong to the main frame of this page`);
    if (options.times === 0)
      return;
    const { uid } = await this._channel.registerLocatorHandler({ selector: locator._selector, noWaitAfter: options.noWaitAfter }, kNoTimeout);
    this._locatorHandlers.set(uid, { locator, handler, times: options.times });
  }

  private async _onLocatorHandlerTriggered(uid: number) {
    let remove = false;
    try {
      const handler = this._locatorHandlers.get(uid);
      if (handler && handler.times !== 0) {
        if (handler.times !== undefined)
          handler.times--;
        await handler.handler(handler.locator);
      }
      remove = handler?.times === 0;
    } finally {
      if (remove)

View on GitHub (pinned to c8fc3bf8d3)

When it happens

Trigger: Thrown at packages/playwright-core/src/client/page.ts:429 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/9e77a8a53b9f3fd8. Report an issue: GitHub.