hashicorp/nomad · error

could not start service - %w

Error message

could not start service - %w

What it means

During a Nomad Windows service upgrade, performInstall stops the old service, replaces the binary, and then calls srvc.Start() to bring the service back up so the new binary is in use. This error wraps any failure from that start attempt via %w, so the underlying Windows service manager error is preserved. It means the binary was installed but the service could not be relaunched.

Source

Thrown at command/windows_service_install.go:241

		if err != nil {
			return fmt.Errorf("unable to create service - %w", err)
		}
		defer srvc.Close()
	}

	// Enable the service in the Windows eventlog
	if err := srvc.EnableEventlog(); err != nil {
		return fmt.Errorf("could not configure eventlog - %w", err)
	}

	// Ensure the service is stopped
	if err := srvc.Stop(); err != nil {
		return fmt.Errorf("could not stop service - %w", err)
	}

	// Start the service so the new binary is in use
	if err := srvc.Start(); err != nil {
		return fmt.Errorf("could not start service - %w", err)
	}

	return nil
}

func (c *WindowsServiceInstallCommand) configInstall(opts *windowsInstallOpts) error {
	// If the config or data directory are unset, default them
	if opts.configDir == "" {
		opts.configDir = filepath.Join(winsvc.WINDOWS_INSTALL_APPDATA_DIRECTORY, "config")
	}
	if opts.dataDir == "" {
		opts.dataDir = filepath.Join(winsvc.WINDOWS_INSTALL_APPDATA_DIRECTORY, "data")
	}

	var err error
	if opts.configDir, err = c.winPaths.Expand(opts.configDir); err != nil {
		return fmt.Errorf("cannot generate configuration path - %s", err)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped %w error to identify the SCM failure reason
2. Verify the installed nomad.exe exists at the service's binPath and is not blocked by antivirus
3. Start the service manually with 'net start nomad' or 'sc start nomad' and check Windows Event Viewer for details
4. Confirm you ran the install from an elevated (Administrator) shell
5. Check the service's Log On account permissions

Example fix

// before: opaque failure at service start
return fmt.Errorf("could not start service - %w", err)
// after: start manually and inspect SCM reason
// C:\> sc start nomad
// C:\> Get-WinEvent -LogName System -MaxEvents 20 | Where-Object {$_.ProviderName -eq 'Service Control Manager'}

// Before install, confirm the service can be started manually
// PowerShell:
$s = Get-Service nomad -ErrorAction SilentlyContinue
if ($s -and $s.Status -eq 'Stopped') { Start-Service nomad; Stop-Service nomad }

err := srvc.Start()
if err != nil {
    return fmt.Errorf("could not start service - %w", err)
}
// Caller: inspect errors.Unwrap(err) / *exec.Error to distinguish path vs permission failures

When it happens

Trigger: Calling 'nomad windows service install' (upgrade path) when srvc.Start() fails after the binary swap — e.g. the service executable path is invalid, the service account lacks permissions, the SCM rejects the start, or the binary is corrupted/locked.

Common situations: Upgrading Nomad while a group policy or antivirus blocks the new nomad.exe; the service's configured binary path was changed manually; insufficient privileges of the installing user; Windows service dependencies not running.

Related errors

• Failed to open Windows eventlog: %w
• timeout exceeded waiting for process
• eventlog.level must be one of INFO, WARN, or ERROR
• running container as ContainerAdmin is unsafe; change the co
• QEMU graceful shutdown is unsupported on the Windows platfor

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