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.

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 c8fc3bf8d3)

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

• Failed to launch webkit because executable doesn't exist at
• Mouse wheel is not supported in mobile WebKit
• Invalid timezone ID: ${contextOptions.timezoneId}
• Cannot take screenshot larger than 32767 pixels on any dimen
• Unknown permission: ${permission}

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