lima-vm/lima · error

instance %q is not running (status: %s)

Error message

instance %q is not running (status: %s)

What it means

`limactl screenshot` needs a running guest to capture the screen. screenshotAction checks inst.Status from store.Inspect and refuses with "instance %q is not running (status: %s)" when the instance is in any state other than Running (stopped, broken, etc.).

Source

Thrown at cmd/limactl/screenshot.go:42

		Short:   "Capture a screenshot of the VM display",
		Args:    WrapArgsError(cobra.ExactArgs(1)),
		RunE:    screenshotAction,
		GroupID: advancedCommand,
	}
	cmd.Flags().StringP("output", "o", "", "Output path; extension must be .png or .bmp (default: INSTANCE-screenshot.png)")
	return cmd
}

func screenshotAction(cmd *cobra.Command, args []string) error {
	instName := args[0]

	ctx := cmd.Context()
	inst, err := store.Inspect(ctx, instName)
	if err != nil {
		return err
	}
	if inst.Status != limatype.StatusRunning {
		return fmt.Errorf("instance %q is not running (status: %s)", instName, inst.Status)
	}

	outputPath, _ := cmd.Flags().GetString("output")
	if outputPath == "" {
		outputPath = instName + "-screenshot.png"
	}

	var format string
	switch strings.ToLower(filepath.Ext(outputPath)) {
	case ".png":
		format = "png"
	case ".bmp":
		format = "bmp"
	default:
		return fmt.Errorf("unsupported output extension %q: must be .png or .bmp", filepath.Ext(outputPath))
	}

	haSock := filepath.Join(inst.Dir, filenames.HostAgentSock)

View on GitHub (pinned to dd909d0973)

Solutions

1. Start the instance first: `limactl start <instance>`, then run `limactl screenshot <instance>`
2. If status is broken, inspect logs (`~/.lima/<instance>/ha.sock` logs / `limactl shell` unavailable) and repair the boot before screenshotting
3. Check current state with `limactl list` to confirm the status before retrying

Example fix

// before
limactl screenshot myvm            # myvm is stopped
// after
limactl start myvm
limactl screenshot myvm

status=$(limactl list --format '{{.Status}}' "$inst" 2>/dev/null)
[ "$status" = "Running" ] || { echo "instance $inst not running (status: ${status:-missing})" >&2; exit 1; }

if err := screenshotCmd.Run(); err != nil {
    if strings.Contains(err.Error(), "is not running") {
        // start the instance and retry the screenshot
    }
}

When it happens

Trigger: Running `limactl screenshot <instance>` while the instance is stopped, starting, broken, or after it crashed.

Common situations: Forgetting to start the VM; attempting a screenshot after a failed boot (status broken); scripting screenshots against an instance that has since shut down; status stale because the hostagent exited.

Related errors

• %w (set video.display to "default" or "vz" to enable screens
• screenshot capture returned no data; GUI window may not be v
• driver %q: %w
• expected status %#q, got %#q

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