{"record":{"id":"4348a10f5405b791","repo":"lima-vm/lima","slug":"failed-to-start-the-instance-q-via-systemctl-w","errorCode":null,"errorMessage":"failed to start the instance %#q via systemctl: %w","messagePattern":"failed to start the instance %#q via systemctl: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/autostart/systemd/systemd.go","lineNumber":62,"sourceCode":"\treturn systemctl(ctx, \"--user\", action, UnitNameFrom(instName))\n}\n\nfunc systemctl(ctx context.Context, args ...string) error {\n\tcmd := exec.CommandContext(ctx, \"systemctl\", args...)\n\tcmd.Stdout = os.Stdout\n\tcmd.Stderr = os.Stderr\n\tlogrus.Debugf(\"running command: %v\", cmd.Args)\n\treturn cmd.Run()\n}\n\n// AutoStartedUnitName returns the systemd service name if the instance is started by systemd.\nfunc AutoStartedUnitName() string {\n\treturn CurrentUnitName()\n}\n\nfunc RequestStart(ctx context.Context, inst *limatype.Instance) error {\n\tif err := systemctl(ctx, \"--user\", \"start\", UnitNameFrom(inst.Name)); err != nil {\n\t\treturn fmt.Errorf(\"failed to start the instance %#q via systemctl: %w\", inst.Name, err)\n\t}\n\treturn nil\n}\n\nfunc RequestStop(ctx context.Context, inst *limatype.Instance) (bool, error) {\n\tif inst.AutoStartedIdentifier == UnitNameFrom(inst.Name) {\n\t\tlogrus.Infof(\"Stopping the instance %#q started by systemd\", inst.Name)\n\t\tif err := systemctl(ctx, \"--user\", \"stop\", inst.AutoStartedIdentifier); err != nil {\n\t\t\treturn false, fmt.Errorf(\"failed to stop the instance %#q via systemctl: %w\", inst.Name, err)\n\t\t}\n\t\treturn true, nil\n\t}\n\treturn false, nil\n}\n","sourceCodeStart":44,"sourceCodeEnd":77,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/autostart/systemd/systemd.go#L44-L77","documentation":"systemd.RequestStart runs `systemctl --user start lima-<instance>.service` to start an auto-started instance; this error wraps a non-zero systemctl exit. The instance was NOT started; the wrapped error contains systemctl's own message (e.g. 'Unit not found' or 'Job failed').","triggerScenarios":"RequestStart called (autostart flow, e.g. `limactl autostart start` or guestagent-driven start) when the user unit lima-<name>.service does not exist, is masked, or its start job fails.","commonSituations":"Autostart entry removed or unit renamed while identifier is stale; systemctl --user unavailable (no user session, LIMA_HOME under a different user, SSH without XDG_RUNTIME_DIR); the VM fails to boot so the start job times out.","solutions":["Run `systemctl --user status lima-<instance>.service` and `journalctl --user -u lima-<instance>.service` to see the root cause","Re-register the autostart entry with `limactl autostart <instance>` so the unit file matches the current unit name","Ensure a user systemd session exists (log in locally; for SSH set XDG_RUNTIME_DIR=/run/user/$(id -u))","Check disk/memory: a failed VM start inside the unit shows as a failed systemctl job"],"exampleFix":"# diagnose and re-register\nsystemctl --user status lima-default.service\nlimactl autostart default\nsystemctl --user start lima-default.service","handlingStrategy":"retry","validationCode":"unit := \"lima-\" + inst.Name + \".service\"\nout, err := exec.Command(\"systemctl\", \"--user\", \"cat\", unit).Output()\nif err != nil {\n    // unit missing/invalid: re-run `limactl autostart <instance>` first\n}\n","typeGuard":null,"tryCatchPattern":"if err := autostart.RequestStart(ctx, inst); err != nil {\n    _ = exec.Command(\"systemctl\", \"--user\", \"daemon-reload\").Run()\n    time.Sleep(2 * time.Second)\n    if err2 := autostart.RequestStart(ctx, inst); err2 != nil {\n        return fmt.Errorf(\"systemctl start failed twice: %w (check journalctl --user -u lima-%s)\", err2, inst.Name)\n    }\n}\n","preventionTips":["Register autostart entries via `limactl autostart <instance>` so unit names stay in sync","Ensure XDG_RUNTIME_DIR is set for SSH/headless sessions; use loginctl enable-linger","After OS upgrades, re-register entries (systemd unit paths/format can change)","Watch journalctl --user for VM start failures surfacing as failed systemctl jobs"],"tags":["systemd","autostart","linux","vm-start"],"backgroundTag":"systemctl-start-failed","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}