{"record":{"id":"d5152117972fa26b","repo":"lima-vm/lima","slug":"screenshot-capture-returned-no-data-gui-window-ma","errorCode":null,"errorMessage":"screenshot capture returned no data; GUI window may not be visible","messagePattern":"screenshot capture returned no data; GUI window may not be visible","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/driver/vz/screenshot_darwin.go","lineNumber":108,"sourceCode":")\n\n// CaptureScreenshot captures the VM display window.\n// format is \"png\" or \"bmp\"; anything else defaults to PNG.\n// Implements driver.Screenshotter. Requires the GUI app bundle to be running.\nfunc (l *LimaVzDriver) CaptureScreenshot(format string) ([]byte, error) {\n\tif !l.canRunGUI() {\n\t\treturn nil, fmt.Errorf(\"%w (set video.display to \\\"default\\\" or \\\"vz\\\" to enable screenshots)\", driver.ErrNoDisplay)\n\t}\n\tuti := \"public.png\"\n\tif format == \"bmp\" {\n\t\tuti = \"com.microsoft.bmp\"\n\t}\n\tcuti := C.CString(uti)\n\tdefer C.freeCString(cuti)\n\tvar outLen C.int\n\tptr := C.captureWindowImageBytes(&outLen, cuti)\n\tif ptr == nil || outLen == 0 {\n\t\treturn nil, errors.New(\"screenshot capture returned no data; GUI window may not be visible\")\n\t}\n\tdefer C.free(ptr)\n\treturn C.GoBytes(ptr, outLen), nil\n}\n","sourceCodeStart":90,"sourceCodeEnd":113,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/vz/screenshot_darwin.go#L90-L113","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// ensure a GUI session exists and screen-recording permission is granted\ntccutil 2>&1 | grep -i screen || true  # check permission state manually in System Settings","typeGuard":null,"tryCatchPattern":"// Go: retry capture after a short delay\nvar img []byte\nfor i := 0; i < 3; i++ {\n    img, err = driver.CaptureScreenshot(\"png\")\n    if err == nil || !strings.Contains(err.Error(), \"returned no data\") { break }\n    time.Sleep(2 * time.Second)\n}","preventionTips":["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"],"tags":["screenshot","vz-driver","macos-permissions"],"backgroundTag":"screenshot-capture-empty","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}