{"record":{"id":"07a088dde4536e9e","repo":"hashicorp/nomad","slug":"qemu-graceful-shutdown-is-unsupported-on-the-windo","errorCode":null,"errorMessage":"QEMU graceful shutdown is unsupported on the Windows platform","messagePattern":"QEMU graceful shutdown is unsupported on the Windows platform","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/qemu/driver.go","lineNumber":555,"sourceCode":"\t}\n\n\tvar netdevArgs []string\n\tif cfg.DNS != nil {\n\t\tif len(cfg.DNS.Servers) > 0 {\n\t\t\tnetdevArgs = append(netdevArgs, \"dns=\"+cfg.DNS.Servers[0])\n\t\t}\n\n\t\tfor _, s := range cfg.DNS.Searches {\n\t\t\tnetdevArgs = append(netdevArgs, \"dnssearch=\"+s)\n\t\t}\n\t}\n\n\ttaskDir := filepath.Join(cfg.AllocDir, cfg.Name)\n\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 {","sourceCodeStart":537,"sourceCodeEnd":573,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/qemu/driver.go#L537-L573","documentation":"The QEMU driver's graceful shutdown feature (driver config graceful_shutdown = true) relies on a monitor socket that is only supported on Unix platforms. On Windows, StartTask rejects the combination with this error rather than silently ignoring the setting.","triggerScenarios":"Starting a QEMU task on a Windows client where the driver configuration sets graceful_shutdown = true; StartTask hits the runtime.GOOS == \"windows\" check before creating the monitor socket path.","commonSituations":"Job/client configs copied from Linux hosts enabling graceful shutdown; fleet-wide driver configs applied to Windows nodes; users expecting QEMU monitor support on Windows.","solutions":["Set graceful_shutdown = false (or omit it) in the QEMU driver config on Windows clients","Scope the graceful_shutdown setting to Linux-only clients via client configuration templating","Use an alternative shutdown mechanism (e.g. ACPI via other means) or run the VM workload on a Linux client"],"exampleFix":"// before\nconfig \"qemu\" {\n  graceful_shutdown = true\n}\n// after\nconfig \"qemu\" {\n  # graceful shutdown unsupported on Windows\n  graceful_shutdown = false\n}","handlingStrategy":"validation","validationCode":"cfg := driverCfg.QemuConfig\nif runtime.GOOS == \"windows\" && cfg.GracefulShutdown {\n    return fmt.Errorf(\"graceful_shutdown is unsupported on Windows; disable it for QEMU tasks\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep Windows and Linux client configs separated; enable graceful_shutdown only on Linux","Lint job/client configs against OS-specific driver capabilities","Document platform limits in QEMU driver configuration docs for your fleet"],"tags":["nomad","qemu","windows","platform-limitation","graceful-shutdown"],"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"}