microsoft/playwright · error · Error

Unknown button: ${button}

Error message

Unknown button: ${button}

What it means

`toBidiButton` maps mouse button names to BiDi codes: left→0, middle→1, right→2. Any other string is rejected. The public API types restrict to 'left'|'right'|'middle', so this is a defensive guard reached mainly through type unsoundness or internal misuse.

Source

Thrown at packages/playwright-core/src/server/bidi/bidiInput.ts:153

export class RawTouchscreenImpl implements input.RawTouchscreen {
  private readonly _session: BidiSession;

  constructor(session: BidiSession) {
    this._session = session;
  }

  async tap(progress: Progress, x: number, y: number, modifiers: Set<types.KeyboardModifier>) {
  }
}

function toBidiButton(button: string): number {
  switch (button) {
    case 'left': return 0;
    case 'right': return 2;
    case 'middle': return 1;
  }
  throw new Error('Unknown button: ' + button);
}

View on GitHub (pinned to c8fc3bf8d3)

Solutions

1. Use only 'left', 'right', or 'middle' for mouse buttons
2. Don't cast button values to `any`
3. Note that back/forward mouse buttons are not currently supported by Playwright/BiDi

Example fix

// before
await page.mouse.down({ button: 'back' as any });

// after
await page.mouse.down({ button: 'middle' });

const BUTTONS = new Set(['left', 'right', 'middle']);
function assertButton(b: string): void {
  if (!BUTTONS.has(b)) throw new Error(`Unsupported mouse button: ${b}`);
}
assertButton(configButton);
await page.mouse.down({ button: configButton });

function isMouseButton(b: unknown): b is 'left' | 'right' | 'middle' {
  return b === 'left' || b === 'right' || b === 'middle';
}

When it happens

Trigger: Calling mouse methods (down/up/click) with a button string outside the allowed set — typically via a cast to `any`, a JS caller passing arbitrary strings, or an internal path forwarding an unvalidated value.

Common situations: Type assertions bypassing `MouseButton`; JavaScript callers passing 'back'/'forward' which Playwright/BiDi don't support; dynamic button selection from config without validation.

Related errors

• Mouse wheel is not supported in mobile WebKit
• Error while parsing selector `${selector}` - cannot use ${op
• url parameter should be string, RegExp, URLPattern or functi
• JSHandle is not a DOM node handle
• Cannot serialize result: object reference chain is too long.

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