grafana/k6 · error

emulating viewport: %w

Error message

emulating viewport: %w

What it means

Viewport emulation builds a Emulation.SetDeviceMetricsOverride action from the configured width/height/deviceScaleFactor/mobile plus screen orientation and screen dimensions, and executes it on the frame's session. This error means that CDP command failed while applying the device metrics.

Source

Thrown at internal/js/modules/k6/browser/common/frame_session.go:1257

		return nil
	}
	viewport := emulatedSize.Viewport
	screen := emulatedSize.Screen

	orientation := emulation.ScreenOrientation{
		Angle: 0.0,
		Type:  emulation.OrientationTypePortraitPrimary,
	}
	if viewport.Width > viewport.Height {
		orientation.Angle = 90.0
		orientation.Type = emulation.OrientationTypeLandscapePrimary
	}
	action := emulation.SetDeviceMetricsOverride(viewport.Width, viewport.Height, opts.DeviceScaleFactor, opts.IsMobile).
		WithScreenOrientation(&orientation).
		WithScreenWidth(screen.Width).
		WithScreenHeight(screen.Height)
	if err := action.Do(cdp.WithExecutor(fs.ctx, fs.session)); err != nil {
		return fmt.Errorf("emulating viewport: %w", err)
	}

	if fs.hasUIWindow {
		// add an inset to viewport depending on the operating system.
		// this won't add an inset if we're running in headless mode.
		viewport = viewport.recalculateInset(
			fs.page.browserCtx.browser.browserOpts.Headless,
			runtime.GOOS,
		)
		action2 := browser.SetWindowBounds(fs.windowID, &browser.Bounds{
			Width:  viewport.Width,
			Height: viewport.Height,
		})
		if err := action2.Do(cdp.WithExecutor(fs.ctx, fs.session)); err != nil {
			return fmt.Errorf("setting window bounds: %w", err)
		}
	}

View on GitHub (pinned to 93accf6570)

Solutions

1. Set an explicit, positive viewport (e.g. { width: 1280, height: 720 }) and a valid deviceScaleFactor
2. Apply the viewport at browser.newPage() time instead of changing it mid-navigation
3. Retry once if the failure coincided with navigation or setup races
4. In headed mode, ensure a real display or xvfb is available so screen metrics are sane

Example fix

// before
const page = await browser.newPage({ viewport: { width: 0, height: 0 } });

// after
const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });

const vp = { width: 1280, height: 720 };
if (!(vp.width > 0 && vp.height > 0)) throw new Error('viewport must be positive');
const page = await browser.newPage({ viewport: vp });

When it happens

Trigger: Creating a page with a viewport option (or updating the viewport) with invalid dimensions such as zero or negative width/height, or executing the action when the target is closing, the browser has disconnected, or the screen-orientation/screen-size parameters are inconsistent for mobile emulation.

Common situations: Mobile/device emulation with unusual viewport configs; empty or defaulted viewport objects producing 0x0; calling viewport changes during teardown; headed runs on minimal window managers where screen metrics lookup returns odd values.

Related errors

• setting window bounds: %w
• WebSocket endpoint cannot be empty
• can't fetch the page for unknown reason
• errorText
• parent frame has been detached

AI-assisted analysis of grafana/k6@93accf6570 (2026-08-15). Data as JSON: /api/errors/d6ff2c24f2b00f2f. Report an issue: GitHub.