What causes "configuration install failed - %w" in hashicorp/nomad?

Verify the parent path of the config directory exists and is writable from an elevated shell

configuration install failed - %w

Error message

configuration install failed - %w

What it means

performInstall wrapper for configInstall failures: creating the configuration directory or writing the basic config file for the Nomad Windows service failed; the wrapped filesystem error gives the cause.

Source

Thrown at command/windows_service_install.go:174

			c.Ui.Output("  Stopping existing nomad service")
			if err := nmdSvc.Stop(); err != nil {
				return fmt.Errorf("unable to stop existing service - %w", err)
			}
		}
	}

	// Install the nomad binary into the system
	if err = c.binaryInstall(opts); err != nil {
		return fmt.Errorf("binary install failed - %w", err)
	}

	c.Ui.Output(fmt.Sprintf("  Nomad binary installed to: %s", opts.binaryPath))

	// Create a configuration directory and add
	// a basic configuration file if no configuration
	// currently exists
	if err = c.configInstall(opts); err != nil {
		return fmt.Errorf("configuration install failed - %w", err)
	}

	c.Ui.Output(fmt.Sprintf("  Nomad configuration directory: %s", opts.configDir))
	c.Ui.Output(fmt.Sprintf("  Nomad agent data directory: %s", opts.configDir))

	// Now let's install that service
	if err := c.serviceInstall(m, opts); err != nil {
		return fmt.Errorf("service install failed - %w", err)
	}

	return nil
}

func (c *WindowsServiceInstallCommand) serviceInstall(m winsvc.WindowsServiceManager, opts *windowsInstallOpts) error {
	var err error
	var srvc winsvc.WindowsService
	cmd := fmt.Sprintf("%s agent -config %s", opts.binaryPath, opts.configDir)

View on GitHub (pinned to 482b49bf1a)

Solutions

Verify the parent path of the config directory exists and is writable from an elevated shell
If -config-dir was given, correct the path (no trailing invalid characters, not a file)
Create the directory manually with correct ACLs, then re-run install
Run the install command as Administrator

Example fix

// before
nomad windows install -config-dir C:\blocked\nomad
// after
nomad windows install -config-dir C:\ProgramData\nomad

Defensive patterns

Strategy: validation

Validate before calling

if fi, err := os.Stat(opts.configDir); err == nil && !fi.IsDir() {
	log.Fatalf("%s exists and is not a directory", opts.configDir)
}
if err := os.MkdirAll(opts.configDir, 0o755); err != nil {
	log.Fatalf("cannot create config dir: %v", err)
}

Try / catch

if err := c.configInstall(opts); err != nil {
	if errors.Is(err, os.ErrPermission) { /* retry elevated */ }
	return fmt.Errorf("configuration install failed - %w", err)
}

Prevention

Verify the -config-dir path is writable by the installing user
Ensure the path is not occupied by a regular file
Pre-create the directory with correct ACLs
Run the installer elevated

When it happens

Trigger: Creating opts.configDir or writing the default config file fails: path invalid, permission denied, or a file exists where a directory is expected.

Common situations: Config dir pointing at a path the user cannot write; an old file occupies the config directory path; group policy or readonly mount blocks creation.

Related errors

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