lima-vm/lima · error

failed to unmarshal instance response: %w

Error message

failed to unmarshal instance response: %w

What it means

handleInspectStatusAction decodes the external driver's stdout JSON and then unmarshals it into a limatype.Instance. This error means the driver produced a response that is valid JSON but does not fit the expected Instance schema — usually a driver/Lima version mismatch or a non-conforming external driver.

Source

Thrown at pkg/driverutil/vm.go:105

	encoder := json.NewEncoder(stdin)
	payload, err := inst.MarshalJSON()
	if err != nil {
		return "", fmt.Errorf("failed to marshal instance config: %w", err)
	}
	if err := encoder.Encode(payload); err != nil {
		return "", err
	}
	stdin.Close()

	decoder := json.NewDecoder(stdout)
	var response []byte
	if err := decoder.Decode(&response); err != nil {
		return "", err
	}

	var respInst limatype.Instance
	if err := respInst.UnmarshalJSON(response); err != nil {
		return "", fmt.Errorf("failed to unmarshal instance response: %w", err)
	}

	if err := cmd.Wait(); err != nil {
		if stderrBuf.Len() > 0 {
			return "", fmt.Errorf("inspect status command failed: %w; stderr: %s", err, stderrBuf.String())
		}
		return "", fmt.Errorf("inspect status command failed: %w", err)
	}

	if stderrBuf.Len() > 0 {
		logrus.Debugf("external driver stderr: %s", stderrBuf.String())
	}

	*inst = respInst
	logrus.Debugf("Inspecting instance status action completed successfully for %#q", extDriverPath)
	return inst.Status, nil
}

View on GitHub (pinned to dd909d0973)

Solutions

1. Align versions: reinstall or upgrade the external driver to match your Lima (v2) build
2. Run the driver's --inspect-status manually and inspect its stdout JSON for schema problems
3. Check the driver's logs/stderr (the previous decode step would fail on non-JSON) and fix driver-side errors
4. Fall back to the built-in driver or recreate the instance if the external driver is broken

Example fix

// before: mismatched plugin
$ limactl plugin install legacy-driver // built for lima v1
// after: rebuild plugin against the v2 module
go build github.com/example/lima-driver-foo@v2-latest

out, err := exec.Command(extDriverPath, "--version").Output()
if err != nil || !compatibleWithCurrentLima(string(out)) {
    return fmt.Errorf("external driver version mismatch with limactl")
}

status, err := driverutil.InspectStatus(ctx, inst)
if err != nil {
    if strings.Contains(err.Error(), "failed to unmarshal instance response") {
        // rebuild/reinstall the external driver against the current Lima version
    }
    return err
}

When it happens

Trigger: The external driver binary returned JSON whose fields do not unmarshal into limatype.Instance (wrong types, unknown format for custom unmarshalers, empty or wrong envelope) via its --inspect-status protocol.

Common situations: External driver built against an older Lima version than the limactl invoking it; a third-party driver emitting a non-standard response; the driver crashed mid-output and stdout contains a partial/error JSON object instead of an Instance.

Related errors

• failed to marshal instance config: %w
• socket must be specified (limactl version mismatch?)
• failed to marshal instance %#q: %w
• failed to write driver PID file: %w
• failed to create driver client: %w

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