{"record":{"id":"e0eeed0f1f82ec36","repo":"hashicorp/nomad","slug":"qemu-guest-agent-socket-is-unsupported-on-the-wind","errorCode":null,"errorMessage":"QEMU Guest Agent socket is unsupported on the Windows platform","messagePattern":"QEMU Guest Agent socket is unsupported on the Windows platform","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/qemu/driver.go","lineNumber":569,"sourceCode":"\n\tvar monitorPath string\n\tif driverConfig.GracefulShutdown {\n\t\tif runtime.GOOS == \"windows\" {\n\t\t\treturn nil, nil, errors.New(\"QEMU graceful shutdown is unsupported on the Windows platform\")\n\t\t}\n\t\t// This socket will be used to manage the virtual machine (for example,\n\t\t// to perform graceful shutdowns)\n\t\tmonitorPath = filepath.Join(taskDir, qemuMonitorSocketName)\n\t\tif err := validateSocketPath(monitorPath); err != nil {\n\t\t\treturn nil, nil, err\n\t\t}\n\t\td.logger.Debug(\"got monitor path\", \"monitorPath\", monitorPath)\n\t\targs = append(args, \"-monitor\", fmt.Sprintf(\"unix:%s,server=on,wait=off\", monitorPath))\n\t}\n\n\tif driverConfig.GuestAgent {\n\t\tif runtime.GOOS == \"windows\" {\n\t\t\treturn nil, nil, errors.New(\"QEMU Guest Agent socket is unsupported on the Windows platform\")\n\t\t}\n\t\t// This socket will be used to communicate with the Guest Agent (if it's running)\n\t\tagentSocketPath := filepath.Join(taskDir, qemuGuestAgentSocketName)\n\t\tif err := validateSocketPath(agentSocketPath); err != nil {\n\t\t\treturn nil, nil, err\n\t\t}\n\n\t\targs = append(args, \"-chardev\", fmt.Sprintf(\"socket,path=%s,server=on,wait=off,id=qga0\", agentSocketPath))\n\t\targs = append(args, \"-device\", \"virtio-serial\")\n\t\targs = append(args, \"-device\", \"virtserialport,chardev=qga0,name=org.qemu.guest_agent.0\")\n\t}\n\n\t// Add pass through arguments to qemu executable. A user can specify\n\t// these arguments in driver task configuration. These arguments are\n\t// passed directly to the qemu driver as command line options.\n\t// For example, args = [ \"-nodefconfig\", \"-nodefaults\" ]\n\t// This will allow a VM with embedded configuration to boot successfully.\n\targs = append(args, driverConfig.Args...)","sourceCodeStart":551,"sourceCodeEnd":587,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/qemu/driver.go#L551-L587","documentation":"The Nomad QEMU driver throws this during StartTask when the task config enables the Guest Agent (driver config \"guest_agent\" = true) but the host OS is Windows. The guest agent is wired up via a unix domain socket passed to QEMU with -qmp/-agent paths, and unix sockets are not supported the same way on Windows, so the driver rejects the configuration before launching the VM.","triggerScenarios":"Calling StartTask on a Windows Nomad client with a QEMU task whose driver config sets guest_agent = true; the check fires immediately after building the monitor args, before any VM process is spawned.","commonSituations":"Teams migrating Nomad clusters from Linux to Windows clients copy-paste Linux job specs; CI pipelines running Windows runners pick up shared HCL job files that enable the guest agent; operators unaware that the QEMU driver's guest-agent feature is Linux-only.","solutions":["Set guest_agent = false (or omit it) in the qemu task driver config on Windows clients","Pin the job to Linux clients with a constraint (kernel.linux = 1 or client.class) so the guest agent config only runs where supported","Run the VM on a Linux Nomad client instead, since guest-agent socket communication requires unix sockets","Remove the guest agent integration and manage the VM without QMP-based agent communication"],"exampleFix":"// before (Windows client job spec)\nconfig {\n  image_path = \"C:\\\\vms\\\\win.qcow2\"\n  guest_agent = true\n}\n// after\nconfig {\n  image_path = \"C:\\\\vms\\\\win.qcow2\"\n  guest_agent = false\n}","handlingStrategy":"validation","validationCode":"// job-spec check before submit (HCL/template pipeline)\nfunc guestAgentAllowed(driverConfig map[string]interface{}, hostOS string) error {\n    if ga, _ := driverConfig[\"guest_agent\"].(bool); ga && hostOS == \"windows\" {\n        return errors.New(\"guest_agent is unsupported on windows; set guest_agent=false\")\n    }\n    return nil\n}","typeGuard":"func windowsHost() bool { return runtime.GOOS == \"windows\" }\nif ga, ok := cfg[\"guest_agent\"].(bool); ok && ga && windowsHost() { /* reject */ }","tryCatchPattern":null,"preventionTips":["Never enable guest_agent in shared job templates used by mixed-OS fleets","Add a job constraint pinning qemu+guest_agent tasks to linux clients","Run nomad job validate on the target client OS class before deploy"],"tags":["qemu","windows","platform-support","nomad-driver"],"backgroundTag":"unsupported-platform-feature","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"}