microsoft/playwright · error · Error

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

Error message

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

What it means

`validateBrowserContextOptions` rejects `noDefaultViewport: true` combined with `isMobile: true`. Mobile emulation needs a viewport to apply the mobile layout metrics.

Source

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

  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();
  return credentials?.find(c => !c.origin || c.origin.toLowerCase() === origin);
}

View on GitHub (pinned to c8fc3bf8d3)

Solutions

1. Remove `isMobile` when using `noDefaultViewport`
2. Or set an explicit viewport to enable mobile emulation

Example fix

// before
await browser.newContext({ viewport: null, isMobile: true });

// after
await browser.newContext({ viewport: { width: 375, height: 667 }, isMobile: true });

const nullVp = opts.viewport === null || !!opts.noDefaultViewport;
if (nullVp && !!opts.isMobile) {
  throw new Error('isMobile requires an explicit viewport; remove noDefaultViewport or unset isMobile.');
}

When it happens

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

Common situations: Combining desktop/windowed mode (null viewport) with mobile emulation flags; partial config merges that keep isMobile from a device-preset.

Related errors

• "deviceScaleFactor" option is not supported with null "viewp
• 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/9537796fccdcb98c. Report an issue: GitHub.