lima-vm/lima · error · driver.ErrNoDisplay

%w (set video.display to "default" or "vz" to enable screens

Error message

%w (set video.display to "default" or "vz" to enable screenshots)

What it means

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.

Source

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

    *outLen = resultLen;
    return result;
}
*/
import "C"

import (
	"errors"
	"fmt"

	"github.com/lima-vm/lima/v2/pkg/driver"
)

// 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

1. Set `video.display: "default"` (or "vz") in the instance's lima.yaml and restart the instance.
2. Ensure the VM is running with the GUI window visible (the VZ app bundle must be active).
3. Use the QEMU driver or a different screenshot mechanism for headless instances.
4. Check `limactl list` that the instance is Running before capturing.

Example fix

// before (lima.yaml)
video:
  display: "none"
// after (lima.yaml)
video:
  display: "default"

// before calling limactl screenshot, confirm display config
grep -A1 'display:' ~/.lima/<instance>/lima.yaml  # expect "default" or "vz"

// Go: test for the sentinel
if errors.Is(err, driver.ErrNoDisplay) {
    // instance has no GUI display; prompt user to set video.display
}

When it happens

Trigger: 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.

Common situations: Users who switched display to headless/virtio-gpu and then try screenshots; headless CI VMs; remote macOS hosts without a GUI session.

Related errors

• screenshot capture returned no data; GUI window may not be v
• instance %q is not running (status: %s)
• failed to get macOS product version: %w
• failed to create a new rosetta directory share caching optio
• vz driver state stopped

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