microsoft/playwright · error · Error

WebKit on Windows has a minimal viewport of 250x240.

Error message

WebKit on Windows has a minimal viewport of 250x240.

What it means

Headful WebKit on Windows enforces a minimum emulated viewport of 250x240 pixels; below that the browser window fails to lay out correctly. _validateEmulatedViewport() throws during context creation or viewport update when width<250 or height<240 on win32+headful.

Solutions

1. Raise the viewport to at least width 250 and height 240 for headful WebKit on Windows.
2. Run WebKit headless on Windows if a smaller viewport is required (the check is gated on headful).
3. Switch the affected tests to chromium/firefox, which do not impose this floor.

Example fix

// before
const ctx = await webkit.launchPersistentContext('', { headless: false, viewport: { width: 200, height: 200 } });

// after
const ctx = await webkit.launchPersistentContext('', { headless: false, viewport: { width: 250, height: 240 } });

const MIN_WK_WIN = { w: 250, h: 240 };
function validWkViewport(viewport, opts) {
  if (process.platform !== 'win32' || !opts.headful) return true;
  return viewport.width >= MIN_WK_WIN.w && viewport.height >= MIN_WK_WIN.h;
}

function isAcceptableWkViewport(v: {width:number;height:number}, headful:boolean): boolean {
  if (process.platform !== 'win32' || !headful) return true;
  return v.width >= 250 && v.height >= 240;
}

When it happens

Trigger: Launching a headful WebKit context on Windows with viewport {width<250} or {height<240}, or calling context.setViewportSize/page.setViewportSize below those bounds. Triggered in _validateEmulatedViewport during context setup.

Common situations: Migrating a config from headless Chromium to headful WebKit on a Windows CI runner with a tiny viewport. Reusing a mobile-emulation viewport (e.g. 200x300) without raising width. Device descriptors with very narrow widths.

Related errors

• Cannot take screenshot larger than 32767 pixels on any…
• Failed to launch webkit because executable doesn't exist at
• Invalid timezone ID
• Mouse wheel is not supported in mobile WebKit
• Unknown permission

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

Appendix: source

Thrown at packages/playwright-core/src/server/webkit/wkBrowser.ts:387

  async doClose(reason: string | undefined): Promise<void | 'close-browser'> {
    if (!this._browserContextId) {
      // Closing persistent context should close the browser.
      return 'close-browser';
    } else {
      await this._browser._browserSession.send('Playwright.deleteContext', { browserContextId: this._browserContextId });
      this._browser._contexts.delete(this._browserContextId);
    }
  }

  async cancelDownload(uuid: string) {
    await this._browser._browserSession.send('Playwright.cancelDownload', { uuid });
  }

  _validateEmulatedViewport(viewportSize: types.Size | undefined) {
    if (!viewportSize)
      return;
    if (process.platform === 'win32' && this._browser.options.headful && (viewportSize.width < 250 || viewportSize.height < 240))
      throw new Error(`WebKit on Windows has a minimal viewport of 250x240.`);
  }
}

View on GitHub (pinned to 312030cdce)