{"record":{"id":"8c23a4d8c109cedb","repo":"lima-vm/lima","slug":"w-set-video-display-to-default-or-vz-to-enab","errorCode":null,"errorMessage":"%w (set video.display to \"default\" or \"vz\" to enable screenshots)","messagePattern":"%w \\(set video\\.display to \"default\" or \"vz\" to enable screenshots\\)","errorType":"error_code","errorClass":"driver.ErrNoDisplay","httpStatus":null,"severity":"error","filePath":"pkg/driver/vz/screenshot_darwin.go","lineNumber":97,"sourceCode":"    *outLen = resultLen;\n    return result;\n}\n*/\nimport \"C\"\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\n\t\"github.com/lima-vm/lima/v2/pkg/driver\"\n)\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":79,"sourceCodeEnd":113,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/vz/screenshot_darwin.go#L79-L113","documentation":"LimaVzDriver.CaptureScreenshot can only capture by snapshotting the GUI window of the running VM app bundle. If the instance is not running with the VZ GUI display (canRunGUI() is false), the driver returns driver.ErrNoDisplay wrapped with a hint to change video.display.","triggerScenarios":"Calling CaptureScreenshot (e.g. `limactl screenshot <instance>`) on an instance whose lima.yaml has video.display set to \"none\" or \"virtio\" instead of \"default\"/\"vz\", or on an instance not running a GUI VZ window.","commonSituations":"Users who switched display to headless/virtio-gpu and then try screenshots; headless CI VMs; remote macOS hosts without a GUI session.","solutions":["Set `video.display: \"default\"` (or \"vz\") in the instance's lima.yaml and restart the instance.","Ensure the VM is running with the GUI window visible (the VZ app bundle must be active).","Use the QEMU driver or a different screenshot mechanism for headless instances.","Check `limactl list` that the instance is Running before capturing."],"exampleFix":"// before (lima.yaml)\nvideo:\n  display: \"none\"\n// after (lima.yaml)\nvideo:\n  display: \"default\"","handlingStrategy":"validation","validationCode":"// before calling limactl screenshot, confirm display config\ngrep -A1 'display:' ~/.lima/<instance>/lima.yaml  # expect \"default\" or \"vz\"","typeGuard":null,"tryCatchPattern":"// Go: test for the sentinel\nif errors.Is(err, driver.ErrNoDisplay) {\n    // instance has no GUI display; prompt user to set video.display\n}","preventionTips":["Keep video.display as \"default\" or \"vz\" if you need screenshots","Confirm the GUI window is running before capturing","Don't rely on screenshots for headless instances"],"tags":["screenshot","vz-driver","gui"],"backgroundTag":"no-display-available","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}