{"record":{"id":"21af7cb6430b1083","repo":"lima-vm/lima","slug":"failed-to-unmarshal-instance-response-w","errorCode":null,"errorMessage":"failed to unmarshal instance response: %w","messagePattern":"failed to unmarshal instance response: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/driverutil/vm.go","lineNumber":105,"sourceCode":"\tencoder := json.NewEncoder(stdin)\n\tpayload, err := inst.MarshalJSON()\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"failed to marshal instance config: %w\", err)\n\t}\n\tif err := encoder.Encode(payload); err != nil {\n\t\treturn \"\", err\n\t}\n\tstdin.Close()\n\n\tdecoder := json.NewDecoder(stdout)\n\tvar response []byte\n\tif err := decoder.Decode(&response); err != nil {\n\t\treturn \"\", err\n\t}\n\n\tvar respInst limatype.Instance\n\tif err := respInst.UnmarshalJSON(response); err != nil {\n\t\treturn \"\", fmt.Errorf(\"failed to unmarshal instance response: %w\", err)\n\t}\n\n\tif err := cmd.Wait(); err != nil {\n\t\tif stderrBuf.Len() > 0 {\n\t\t\treturn \"\", fmt.Errorf(\"inspect status command failed: %w; stderr: %s\", err, stderrBuf.String())\n\t\t}\n\t\treturn \"\", fmt.Errorf(\"inspect status command failed: %w\", err)\n\t}\n\n\tif stderrBuf.Len() > 0 {\n\t\tlogrus.Debugf(\"external driver stderr: %s\", stderrBuf.String())\n\t}\n\n\t*inst = respInst\n\tlogrus.Debugf(\"Inspecting instance status action completed successfully for %#q\", extDriverPath)\n\treturn inst.Status, nil\n}\n","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driverutil/vm.go#L87-L123","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Align versions: reinstall or upgrade the external driver to match your Lima (v2) build","Run the driver's --inspect-status manually and inspect its stdout JSON for schema problems","Check the driver's logs/stderr (the previous decode step would fail on non-JSON) and fix driver-side errors","Fall back to the built-in driver or recreate the instance if the external driver is broken"],"exampleFix":"// before: mismatched plugin\n$ limactl plugin install legacy-driver // built for lima v1\n// after: rebuild plugin against the v2 module\ngo build github.com/example/lima-driver-foo@v2-latest","handlingStrategy":"try-catch","validationCode":"out, err := exec.Command(extDriverPath, \"--version\").Output()\nif err != nil || !compatibleWithCurrentLima(string(out)) {\n    return fmt.Errorf(\"external driver version mismatch with limactl\")\n}","typeGuard":null,"tryCatchPattern":"status, err := driverutil.InspectStatus(ctx, inst)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to unmarshal instance response\") {\n        // rebuild/reinstall the external driver against the current Lima version\n    }\n    return err\n}","preventionTips":["Build external drivers from the same Lima module version as limactl","After upgrading Lima, upgrade all installed driver plugins","Smoke-test `driver --inspect-status` with a sample Instance JSON in CI"],"tags":["json","external-driver","version-mismatch"],"backgroundTag":"json-schema-mismatch","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}