hashicorp/nomad · error

QEMU Guest Agent socket is unsupported on the Windows platfo

Error message

QEMU Guest Agent socket is unsupported on the Windows platform

What it means

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.

Source

Thrown at drivers/qemu/driver.go:569

	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 {
			return nil, nil, err
		}

		args = append(args, "-chardev", fmt.Sprintf("socket,path=%s,server=on,wait=off,id=qga0", agentSocketPath))
		args = append(args, "-device", "virtio-serial")
		args = append(args, "-device", "virtserialport,chardev=qga0,name=org.qemu.guest_agent.0")
	}

	// Add pass through arguments to qemu executable. A user can specify
	// these arguments in driver task configuration. These arguments are
	// passed directly to the qemu driver as command line options.
	// For example, args = [ "-nodefconfig", "-nodefaults" ]
	// This will allow a VM with embedded configuration to boot successfully.
	args = append(args, driverConfig.Args...)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set guest_agent = false (or omit it) in the qemu task driver config on Windows clients
2. Pin the job to Linux clients with a constraint (kernel.linux = 1 or client.class) so the guest agent config only runs where supported
3. Run the VM on a Linux Nomad client instead, since guest-agent socket communication requires unix sockets
4. Remove the guest agent integration and manage the VM without QMP-based agent communication

Example fix

// before (Windows client job spec)
config {
  image_path = "C:\\vms\\win.qcow2"
  guest_agent = true
}
// after
config {
  image_path = "C:\\vms\\win.qcow2"
  guest_agent = false
}

// job-spec check before submit (HCL/template pipeline)
func guestAgentAllowed(driverConfig map[string]interface{}, hostOS string) error {
    if ga, _ := driverConfig["guest_agent"].(bool); ga && hostOS == "windows" {
        return errors.New("guest_agent is unsupported on windows; set guest_agent=false")
    }
    return nil
}

func windowsHost() bool { return runtime.GOOS == "windows" }
if ga, ok := cfg["guest_agent"].(bool); ok && ga && windowsHost() { /* reject */ }

When it happens

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

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

Related errors

• QEMU graceful shutdown is unsupported on the Windows platfor
• KVM accelerator is unsupported on the current platform
• monitorPath not set
• executor Shutdown failed: %v
• cannot destroy running task

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