microsoft/playwright · error · Error

Invalid viewport size format: use "width,height", for exampl

Error message

Invalid viewport size format: use "width,height", for example --viewport-size="800,600"

What it means

Thrown by the `--viewport-size` CLI option handler in browserActions when splitting the value into width,height fails to yield two finite numbers. The handler does `value.split(',').map(n => +n)` and throws a sentinel 'bad values' error inside a try, rethrown as the user-facing format message.

Source

Thrown at packages/playwright-core/src/cli/browserActions.ts:109

  // Proxy

  if (options.proxyServer) {
    launchOptions.proxy = {
      server: options.proxyServer
    };
    if (options.proxyBypass)
      launchOptions.proxy.bypass = options.proxyBypass;
  }

  // Viewport size
  if (options.viewportSize) {
    try {
      const [width, height] = options.viewportSize.split(',').map(n => +n);
      if (isNaN(width) || isNaN(height))
        throw new Error('bad values');
      contextOptions.viewport = { width, height };
    } catch (e) {
      throw new Error('Invalid viewport size format: use "width,height", for example --viewport-size="800,600"');
    }
  }

  // Geolocation

  if (options.geolocation) {
    try {
      const [latitude, longitude] = options.geolocation.split(',').map(n => parseFloat(n.trim()));
      contextOptions.geolocation = {
        latitude,
        longitude
      };
    } catch (e) {
      throw new Error('Invalid geolocation format, should be "lat,long". For example --geolocation="37.819722,-122.478611"');
    }
    contextOptions.permissions = ['geolocation'];
  }

View on GitHub (pinned to c8fc3bf8d3)

Solutions

Use the `width,height` form exactly, e.g. `--viewport-size="800,600"`.
If sourcing from an env var, validate/transform it before passing to the CLI.
Quote the value to avoid shell splitting.

Example fix

# before
npx playwright open --viewport-size=800x600 https://example.com

# after
npx playwright open --viewport-size="800,600" https://example.com

Defensive patterns

Strategy: validation

Validate before calling

function parseViewportSize(raw: string): { width: number; height: number } {
  const parts = (raw ?? '').split(',');
  if (parts.length !== 2) throw new Error('Use "width,height" e.g. "800,600"');
  const [w, h] = parts.map(Number);
  if (!Number.isFinite(w) || !Number.isFinite(h) || w <= 0 || h <= 0)
    throw new Error('width and height must be positive numbers');
  return { width: w, height: h };
}

Type guard

function isViewportString(v: string): boolean {
  const m = v.match(/^(\d+),(\d+)$/);
  return !!m && +m[1] > 0 && +m[2] > 0;
}

Try / catch

try {
  return parseViewportSize(raw);
} catch (e) {
  if (/Invalid viewport size format/.test(e.message)) {
    throw new Error(`Expected "W,H" (e.g. "800,600"), got ${JSON.stringify(raw)}`);
  }
  throw e;
}

Prevention

Validate the env-supplied viewport before forwarding it to the CLI.
Quote `--viewport-size="800,600"` so the shell does not split it.
Normalize locale-specific separators to a comma.

When it happens

Trigger: Running `playwright open --viewport-size=...` (or screenshot/pdf commands) with a value missing the comma, non-numeric components, or empty string: `--viewport-size=800`, `--viewport-size=800,x`, `--viewport-size=abc,def`.

Common situations: Typo omitting the comma; locale using a different separator; copy-pasting a `WxH` form instead of `W,H`; empty env var feeding the flag.

Related errors

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