grafana/k6 · error

clip area is either empty or outside the viewport

Error message

clip area is either empty or outside the viewport

What it means

The screenshotter intersects the requested clip rectangle with the current viewport (screenshotter.go:443-456). If the intersection has zero width or height — the clip is empty or lies entirely outside the viewport — the screenshot is refused with 'clip area is either empty or outside the viewport'.

Source

Thrown at internal/js/modules/k6/browser/common/screenshotter.go:453

}

func (s *screenshotter) trimClipToSize(clip *Rect, size *Size) (*Rect, error) {
	p1 := Position{
		X: math.Max(0, math.Min(clip.X, size.Width)),
		Y: math.Max(0, math.Min(clip.Y, size.Height)),
	}
	p2 := Position{
		X: math.Max(0, math.Min(clip.X+clip.Width, size.Width)),
		Y: math.Max(0, math.Min(clip.Y+clip.Height, size.Height)),
	}
	result := Rect{
		X:      p1.X,
		Y:      p1.Y,
		Width:  p2.X - p1.X,
		Height: p2.Y - p1.Y,
	}
	if result.Width == 0 || result.Height == 0 {
		return nil, errors.New("clip area is either empty or outside the viewport")
	}
	return &result, nil
}

View on GitHub (pinned to 93accf6570)

Solutions

1. Set fullPage: true when the target area lies outside the current viewport
2. Ensure clip width and height are strictly positive
3. Clamp x/y to the viewport: use Math.max(0, ...) on both axes and the dimensions
4. Prefer locator.screenshot()/elementHandle.screenshot(), which computes the rectangle for you

Example fix

// before
await page.screenshot({ clip: { x: 0, y: 1200, width: 300, height: 200 } }); // below the fold

// after
await page.screenshot({ fullPage: true, clip: { x: 0, y: 1200, width: 300, height: 200 } });

// Intersect the clip with the viewport before shooting
const vp = page.viewportSize();
const x = Math.max(0, clip.x), y = Math.max(0, clip.y);
const w = Math.min(clip.width, vp.width - x), h = Math.min(clip.height, vp.height - y);
if (w > 0 && h > 0) { await page.screenshot({ clip: { x, y, width: w, height: h } }); }
else { await page.screenshot({ fullPage: true, clip }); }

When it happens

Trigger: page.screenshot({ clip: {...} }) with width or height 0; clip coordinates beyond the viewport (e.g. y below the fold while fullPage is false); negative x/y pushing the rectangle fully off-screen; coordinates computed for a different viewport size or device scale factor.

Common situations: Capturing elements below the fold without fullPage; clip rects derived from getBoundingClientRect after the page scrolled; viewport resized between measuring and shooting; high-DPI coordinate math mistakes.

Related errors

• setting viewport size: %w
• unmarshalling image format: %w
• unpacking window size: %w
• getting original viewport size: %w
• predicate function is not callable

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