grafana/k6 · error

updateViewport should be called only in the main frame. (sid

Error message

updateViewport should be called only in the main frame. (sid:%v tid:%v)

What it means

A deliberate internal sanity-check sentinel: updateViewport applies device metrics only to the top-level page target, and this error is returned when the method is invoked on a FrameSession whose target is an iframe or another out-of-process child frame (isMainFrame() is false). It signals a k6-internal misuse of the API, not anything the user's script can directly control; session and target IDs are included for debugging.

Source

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

}

func (fs *FrameSession) updateRequestInterception(enable bool) error {
	fs.logger.Debugf("NewFrameSession:updateRequestInterception",
		"sid:%v tid:%v on:%v",
		fs.session.ID(),
		fs.targetID, enable)

	return fs.networkManager.setRequestInterception(enable)
}

func (fs *FrameSession) updateViewport() error {
	fs.logger.Debugf("NewFrameSession:updateViewport", "sid:%v tid:%v", fs.session.ID(), fs.targetID)

	// other frames don't have viewports and,
	// this method shouldn't be called for them.
	// this is just a sanity check.
	if !fs.isMainFrame() {
		err := fmt.Errorf("updateViewport should be called only in the main frame."+
			" (sid:%v tid:%v)", fs.session.ID(), fs.targetID)
		panic(err)
	}

	opts := fs.page.browserCtx.opts
	emulatedSize := fs.page.emulatedSize
	if emulatedSize == nil {
		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

View on GitHub (pinned to 94169daab2)

Solutions

1. Do not attempt viewport operations on child frames — call viewport-related APIs (setViewportSize, emulateMedia size) on the page object
2. Report the issue with the session/target IDs if it occurs during normal page usage, as it indicates a bug in k6's frame session lifecycle
3. Update to a newer k6 version where frame-session handling for iframes has been fixed

When it happens

Trigger: Thrown at internal/js/modules/k6/browser/common/frame_session.go:1231 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of grafana/k6@94169daab2 (2026-08-18). Data as JSON: /api/errors/b68c46935c9be3fb. Report an issue: GitHub.