microsoft/playwright · error · Error

"deviceScaleFactor" option is not supported with null "viewp

Error message

"deviceScaleFactor" option is not supported with null "viewport"

What it means

`validateBrowserContextOptions` rejects combining `noDefaultViewport: true` (null viewport) with `deviceScaleFactor`, because without a viewport Playwright cannot apply a device scale factor — the browser window itself is the viewport.

Source

Thrown at packages/playwright-core/src/server/browserContext.ts:760

    await Promise.all(this.pages().map(page => page.safeNonStallingEvaluateInAllFrames(expression, world, options)));
  }

  addRouteInFlight(route: network.Route) {
    this._routesInFlight.add(route);
  }

  removeRouteInFlight(route: network.Route) {
    this._routesInFlight.delete(route);
  }

  async notifyRoutesInFlightAboutRemovedHandler(handler: network.RouteHandler): Promise<void> {
    await Promise.all([...this._routesInFlight].map(route => route.removeHandler(handler)));
  }
}

export function validateBrowserContextOptions(options: types.BrowserContextOptions, browserOptions: BrowserOptions) {
  if (options.noDefaultViewport && options.deviceScaleFactor !== undefined)
    throw new Error(`"deviceScaleFactor" option is not supported with null "viewport"`);
  if (options.noDefaultViewport && !!options.isMobile)
    throw new Error(`"isMobile" option is not supported with null "viewport"`);
  if (options.acceptDownloads === undefined && browserOptions.name !== 'electron')
    options.acceptDownloads = 'accept';
  // Electron requires explicit acceptDownloads: true since we wait for
  // https://github.com/electron/electron/pull/41718 to be widely shipped.
  // In 6-12 months, we can remove this check.
  else if (options.acceptDownloads === undefined && browserOptions.name === 'electron')
    options.acceptDownloads = 'internal-browser-default';
  if (!options.viewport && !options.noDefaultViewport)
    options.viewport = { width: 1280, height: 720 };
  if (options.proxy)
    options.proxy = normalizeProxySettings(options.proxy);
  verifyGeolocation(options.geolocation);
}

export function findMatchingHttpCredentials(credentials: HttpCredentials[] | undefined, url: string): HttpCredentials | undefined {
  const origin = new URL(url).origin.toLowerCase();

View on GitHub (pinned to c8fc3bf8d3)

Solutions

1. Remove `deviceScaleFactor` when using `noDefaultViewport` / `viewport: null`
2. Or set an explicit viewport so deviceScaleFactor applies

Example fix

// before
await browser.newContext({ viewport: null, deviceScaleFactor: 2 });

// after
await browser.newContext({ viewport: null });

function validateContextOpts(o: { viewport?: null; noDefaultViewport?: boolean; deviceScaleFactor?: number; isMobile?: boolean }) {
  const nullVp = o.viewport === null || !!o.noDefaultViewport;
  if (nullVp && o.deviceScaleFactor !== undefined)
    throw new Error('deviceScaleFactor requires a viewport (remove noDefaultViewport).');
  if (nullVp && !!o.isMobile)
    throw new Error('isMobile requires a viewport (remove noDefaultViewport).');
}

When it happens

Trigger: `browser.newContext({ noDefaultViewport: true, deviceScaleFactor: 2 })` or `{ viewport: null, deviceScaleFactor: 2 }`.

Common situations: Switching to headless/windowed mode with `viewport: null` while keeping deviceScaleFactor from a previous config; desktop-automation setups reusing mobile configs.

Related errors

• "isMobile" option is not supported with null "viewport"
• Invalid resolution format: use ${name}="800x600"
• Invalid viewport size format: use "width,height", for exampl
• geolocation.longitude: precondition -180 <= LONGITUDE <= 180
• geolocation.latitude: precondition -90 <= LATITUDE <= 90 fai

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