hashicorp/nomad · error

QEMU graceful shutdown is unsupported on the Windows platfor

Error message

QEMU graceful shutdown is unsupported on the Windows platform

What it means

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.

Source

Thrown at drivers/qemu/driver.go:555

	}

	var netdevArgs []string
	if cfg.DNS != nil {
		if len(cfg.DNS.Servers) > 0 {
			netdevArgs = append(netdevArgs, "dns="+cfg.DNS.Servers[0])
		}

		for _, s := range cfg.DNS.Searches {
			netdevArgs = append(netdevArgs, "dnssearch="+s)
		}
	}

	taskDir := filepath.Join(cfg.AllocDir, cfg.Name)

	var monitorPath string
	if driverConfig.GracefulShutdown {
		if runtime.GOOS == "windows" {
			return nil, nil, errors.New("QEMU graceful shutdown is unsupported on the Windows platform")
		}
		// This socket will be used to manage the virtual machine (for example,
		// to perform graceful shutdowns)
		monitorPath = filepath.Join(taskDir, qemuMonitorSocketName)
		if err := validateSocketPath(monitorPath); err != nil {
			return nil, nil, err
		}
		d.logger.Debug("got monitor path", "monitorPath", monitorPath)
		args = append(args, "-monitor", fmt.Sprintf("unix:%s,server=on,wait=off", monitorPath))
	}

	if driverConfig.GuestAgent {
		if runtime.GOOS == "windows" {
			return nil, nil, errors.New("QEMU Guest Agent socket is unsupported on the Windows platform")
		}
		// This socket will be used to communicate with the Guest Agent (if it's running)
		agentSocketPath := filepath.Join(taskDir, qemuGuestAgentSocketName)
		if err := validateSocketPath(agentSocketPath); err != nil {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set graceful_shutdown = false (or omit it) in the QEMU driver config on Windows clients
2. Scope the graceful_shutdown setting to Linux-only clients via client configuration templating
3. Use an alternative shutdown mechanism (e.g. ACPI via other means) or run the VM workload on a Linux client

Example fix

// before
config "qemu" {
  graceful_shutdown = true
}
// after
config "qemu" {
  # graceful shutdown unsupported on Windows
  graceful_shutdown = false
}

cfg := driverCfg.QemuConfig
if runtime.GOOS == "windows" && cfg.GracefulShutdown {
    return fmt.Errorf("graceful_shutdown is unsupported on Windows; disable it for QEMU tasks")
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• running container as ContainerAdmin is unsafe; change the co
• QEMU Guest Agent socket is unsupported on the Windows platfo
• KVM accelerator is unsupported on the current platform
• user name must contain domain
• executor Shutdown failed: %v

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/07a088dde4536e9e. Report an issue: GitHub.