screenshot capture returned no data; GUI window may not be v

Error message

screenshot capture returned no data; GUI window may not be visible

What it means

CaptureScreenshot invokes the C helper captureWindowImageBytes, which grabs the VZ GUI window image. If the helper returns a nil pointer or zero length, there was no window pixels to capture, and the driver returns this error indicating the GUI window may not be visible.

Source

Thrown at pkg/driver/vz/screenshot_darwin.go:108

)

// CaptureScreenshot captures the VM display window.
// format is "png" or "bmp"; anything else defaults to PNG.
// Implements driver.Screenshotter. Requires the GUI app bundle to be running.
func (l *LimaVzDriver) CaptureScreenshot(format string) ([]byte, error) {
	if !l.canRunGUI() {
		return nil, fmt.Errorf("%w (set video.display to \"default\" or \"vz\" to enable screenshots)", driver.ErrNoDisplay)
	}
	uti := "public.png"
	if format == "bmp" {
		uti = "com.microsoft.bmp"
	}
	cuti := C.CString(uti)
	defer C.freeCString(cuti)
	var outLen C.int
	ptr := C.captureWindowImageBytes(&outLen, cuti)
	if ptr == nil || outLen == 0 {
		return nil, errors.New("screenshot capture returned no data; GUI window may not be visible")
	}
	defer C.free(ptr)
	return C.GoBytes(ptr, outLen), nil
}

View on GitHub (pinned to dd909d0973)

Solutions

Make sure the VZ VM window is open and visible on the host GUI session before capturing.
Grant Screen Recording permission (System Settings > Privacy & Security) to the terminal/app running limactl.
Retry after the window renders (wait a few seconds after boot).
Run limactl from a GUI session rather than an SSH/headless context.

Defensive patterns

Strategy: retry

Validate before calling

// ensure a GUI session exists and screen-recording permission is granted
tccutil 2>&1 | grep -i screen || true  # check permission state manually in System Settings

Try / catch

// Go: retry capture after a short delay
var img []byte
for i := 0; i < 3; i++ {
    img, err = driver.CaptureScreenshot("png")
    if err == nil || !strings.Contains(err.Error(), "returned no data") { break }
    time.Sleep(2 * time.Second)
}

Prevention

Grant Screen Recording permission to the terminal/app
Keep the VZ window visible (not minimized) during capture
Wait for window render after boot before capturing
Capture from a GUI session, not SSH

When it happens

Trigger: Calling CaptureScreenshot while the VM runs with a VZ display but the window is minimized, hidden, on another virtual desktop, off-screen, or the app bundle lacks screen-capture permission.

Common situations: Headless SSH sessions into the macOS host with no logged-in GUI user; macOS Screen Recording permission not granted to limactl/the app bundle; window minimized at capture time; the VM just started and the window hasn't rendered yet.

Related errors

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/d5152117972fa26b. Report an issue: GitHub.