{"record":{"id":"9d9d3e42408af799","repo":"hashicorp/nomad","slug":"monitorpath-not-set","errorCode":null,"errorMessage":"monitorPath not set","messagePattern":"monitorPath not set","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/qemu/driver.go","lineNumber":874,"sourceCode":"}\n\n// validateSocketPath provides best effort validation of socket paths since\n// some rules may be platform-dependant.\nfunc validateSocketPath(path string) error {\n\tif maxSocketPathLen > 0 && len(path) > maxSocketPathLen {\n\t\treturn fmt.Errorf(\n\t\t\t\"socket path %s is longer than the maximum length allowed (%d), try to reduce the task name or Nomad's data_dir if possible.\",\n\t\t\tpath, maxSocketPathLen)\n\t}\n\n\treturn nil\n}\n\n// sendQemuShutdown attempts to issue an ACPI power-off command via the qemu\n// monitor\nfunc sendQemuShutdown(logger hclog.Logger, monitorPath string, userPid int) error {\n\tif monitorPath == \"\" {\n\t\treturn errors.New(\"monitorPath not set\")\n\t}\n\tmonitorSocket, err := net.Dial(\"unix\", monitorPath)\n\tif err != nil {\n\t\tlogger.Warn(\"could not connect to qemu monitor\", \"pid\", userPid, \"monitorPath\", monitorPath, \"error\", err)\n\t\treturn err\n\t}\n\tdefer monitorSocket.Close()\n\tlogger.Debug(\"sending graceful shutdown command to qemu monitor socket\", \"monitor_path\", monitorPath, \"pid\", userPid)\n\t_, err = monitorSocket.Write([]byte(qemuGracefulShutdownMsg))\n\tif err != nil {\n\t\tlogger.Warn(\"failed to send shutdown message\", \"shutdown message\", qemuGracefulShutdownMsg, \"monitorPath\", monitorPath, \"userPid\", userPid, \"error\", err)\n\t}\n\treturn err\n}\n","sourceCodeStart":856,"sourceCodeEnd":889,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/qemu/driver.go#L856-L889","documentation":"sendQemuShutdown, used by the QEMU driver's StopTask to issue an ACPI power-off through the QEMU monitor socket, requires the monitorPath of the unix socket QEMU was started with. If the path is empty the graceful shutdown cannot proceed, so it returns this error and StopTask falls back to force-killing the process.","triggerScenarios":"StopTask invoking sendQemuShutdown with an empty monitorPath — typically because the task was started without a monitor socket (driver config \"monitor\" disabled or absent), the handle's monitor path was never persisted, or state was recovered from an older handle that lacks it.","commonSituations":"Tasks started before a monitor config change are later stopped; restored handles after Nomad client restart where monitor_path is empty; configs that explicitly disable the QEMU monitor; operators seeing slow stops because every shutdown degrades to SIGKILL.","solutions":["Enable the monitor in the qemu driver config so a monitor socket path is allocated at StartTask","Stop and restart the task so a fresh handle with a valid monitorPath is created","Check whether the running Nomad version persists monitor_path in the driver handle and upgrade if the task predates that fix","Accept the fallback: ensure the app inside the VM handles SIGKILL gracefully or rely on the forced kill"],"exampleFix":"// before (config without monitor)\nconfig {\n  image_path = \".../disk.qcow2\"\n}\n// after\nconfig {\n  image_path = \".../disk.qcow2\"\n  args = [\"-monitor\", \"unix:/tmp/vm-monitor.sock,server=on,wait=off\"]\n}","handlingStrategy":"try-catch","validationCode":"// before StopTask, verify the handle carries a monitor path\nif h.MonitorPath == \"\" {\n    log.Warn(\"no qemu monitor socket; stop will force-kill\")\n}","typeGuard":"func hasMonitorPath(p string) bool { return p != \"\" }","tryCatchPattern":"err := task.Stop(ctx)\nvar missing interface{ Error() string }\nif err != nil && strings.Contains(err.Error(), \"monitorPath not set\") {\n    log.Warn(\"graceful ACPI shutdown unavailable; QEMU was force-killed\")\n} else if err != nil {\n    return err\n}","preventionTips":["Keep the qemu monitor enabled so every task gets a monitor socket","Recreate tasks whose handles predate monitor-path persistence","Alert on force-kill fallbacks in client logs to spot missing monitor configs"],"tags":["qemu","shutdown","monitor-socket","nomad-driver"],"backgroundTag":"missing-required-argument","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}