lima-vm/lima · error

driver %q: %w

Error message

driver %q: %w

What it means

HostAgent.Screenshot requires the active driver to implement the driver.Screenshotter interface (CaptureScreenshot). If the underlying driver (after unwrapping ConfiguredDriver) does not support screenshots, this error wrapping ErrDriverNotScreenshotter is returned naming the driver.

Source

Thrown at pkg/hostagent/hostagent.go:551

	if closeErr := a.close(); closeErr != nil {
		logrus.WithError(closeErr).Warn("an error during shutting down the host agent")
	}
	cancelHA()
	stopErr := a.driver.Stop(ctx)
	// Stop the external driver gRPC server now that the instance is shutting down.
	server.Stop(a.instDir, false)
	return stopErr
}

func (a *HostAgent) Screenshot(ctx context.Context, format string) ([]byte, error) {
	// ConfiguredDriver wraps the concrete driver; unwrap to reach optional interfaces.
	inner := a.driver
	if cd, ok := a.driver.(*driver.ConfiguredDriver); ok {
		inner = cd.Driver
	}
	s, ok := inner.(driver.Screenshotter)
	if !ok {
		return nil, fmt.Errorf("driver %q: %w", a.driver.Info(ctx).Name, driver.ErrDriverNotScreenshotter)
	}
	return s.CaptureScreenshot(format)
}

func (a *HostAgent) Info(_ context.Context) (*hostagentapi.Info, error) {
	info := &hostagentapi.Info{
		AutoStartedIdentifier: autostart.AutoStartedIdentifier(),
		SSHLocalPort:          a.sshLocalPort,
	}
	return info, nil
}

func (a *HostAgent) sshAddressPort() (sshAddress string, sshPort int) {
	sshAddress = a.instSSHAddress
	sshPort = a.sshLocalPort
	return sshAddress, sshPort
}

View on GitHub (pinned to dd909d0973)

Solutions

1. Use a backend that supports screenshots (qemu or vz on macOS) if you need limactl screenshot
2. Check Lima release notes / driver docs for which vmType implements Screenshotter
3. Use an alternative screen-capture route for the VM (e.g. VNC/display forwarding) when your driver lacks support

Example fix

// before (lima.yaml)
vmType: "wsl2"   # no screenshot support
// after
vmType: "qemu"

// before calling screenshot, check driver support
drv := a.driver
if cd, ok := drv.(*driver.ConfiguredDriver); ok { drv = cd.Driver }
if _, ok := drv.(driver.Screenshotter); !ok {
	return fmt.Errorf("screenshots unsupported for vmType %q", inst.Config.VMType)
}

func supportsScreenshot(d driver.Driver) bool {
	_, ok := d.(driver.Screenshotter)
	return ok
}

img, err := ha.Screenshot(ctx, format)
if errors.Is(err, driver.ErrDriverNotScreenshotter) {
	return nil, fmt.Errorf("use qemu/vz for screenshots: %w", err)
}

When it happens

Trigger: Calling 'limactl screenshot <instance>' (or the Screenshot API) on an instance whose vmType/driver has no screenshot capability — e.g. a driver backend that has not implemented CaptureScreenshot.

Common situations: Requesting a screenshot on wsl2 or other backends lacking screenshot support; running limactl screenshot against an instance on a platform where only qemu/vz implement it; driver feature mismatch after switching vmType.

Related errors

• instance %q is not running (status: %s)
• failed to get boot scripts: %w
• invalid boot script filename %#q: must be in format 'boot.<O
• unimplemented by the krunkit driver
• %w (set video.display to "default" or "vz" to enable screens

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