hashicorp/nomad · error

failed to create executor: %v

Error message

failed to create executor: %v

What it means

StartTask creates a go-plugin executor subprocess (executor.CreateExecutor) that will supervise the java process. If the executor plugin cannot be created — plugin binary missing, handshake failure, bad nomadConfig/executorConfig — the error is wrapped with this message. The deferred pluginClient.Kill() prevents leaking the executor on later failures.

Source

Thrown at drivers/java/driver.go:495

		if err != nil {
			return nil, nil, fmt.Errorf("failed to build mount for resolv.conf: %v", err)
		}
		cfg.Mounts = append(cfg.Mounts, dnsMount)
	}

	caps, err := capabilities.Calculate(
		capabilities.NomadDefaults(), d.config.AllowCaps, driverConfig.CapAdd, driverConfig.CapDrop,
	)
	if err != nil {
		return nil, nil, err
	}
	d.logger.Debug("task capabilities", "capabilities", caps)

	exec, pluginClient, err := executor.CreateExecutor(
		d.logger.With("task_name", handle.Config.Name, "alloc_id", handle.Config.AllocID),
		d.nomadConfig, executorConfig)
	if err != nil {
		return nil, nil, fmt.Errorf("failed to create executor: %v", err)
	}
	// prevent leaking executor in error scenarios
	defer func() {
		if err != nil {
			pluginClient.Kill()
		}
	}()

	execCmd := &executor.ExecCommand{
		Cmd:              absPath,
		Args:             args,
		Env:              cfg.EnvList(),
		User:             user,
		ResourceLimits:   true,
		Resources:        cfg.Resources,
		TaskDir:          cfg.TaskDir().Dir,
		WorkDir:          driverConfig.WorkDir,
		StdoutPath:       cfg.StdoutPath,

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Restart the Nomad client to restore the executor plugin (re-extract/re-hash plugins).
2. Ensure the Nomad client installation is intact and all versions match (no partially upgraded binaries).
3. Check that the task dir is writable so executor.out can be created.
4. Inspect client logs at debug level for the underlying go-plugin handshake error (e.g. timeout, protocol mismatch) and fix per that root cause.

Example fix

# before: 'failed to create executor: dial unix .../executor.sock: connect: connection refused'
# after: reinstall/repair client binaries and restart
sudo systemctl restart nomad
# verify plugin loads
nomad node status -verbose | grep -i driver

// preflight: confirm executor plugin exists and client is healthy
if _, err := os.Stat(filepath.Join(nomadPluginDir, "executor")); err != nil {
    return fmt.Errorf("executor plugin missing from plugin_dir: %w", err)
}
if err := os.MkdirAll(taskDir, 0o755); err != nil {
    return fmt.Errorf("cannot write executor.out in task dir: %w", err)
}

_, _, err := driver.StartTask(cfg)
if err != nil && strings.Contains(err.Error(), "failed to create executor") {
    // restart/repair the Nomad client; check version skew
    return RetryAfterClientRepair(fmt.Errorf("executor plugin failed to start: %w", err))
}

When it happens

Trigger: Calling StartTask when executor.CreateExecutor fails: the nomad executor plugin binary is absent/mismatched, the plugin handshake times out, executorConfig (LogFile, FSIsolation, Compute) is invalid, or the executor log file path can't be used.

Common situations: Nomad version skew between client and executor plugin; corrupted or replaced nomad installation; running in restricted containers where spawning the plugin process or writing executor.out fails; FSIsolation mismatch (chroot on hosts without the chroot content).

Related errors

• failed to create executor: %v
• failed to build ReattachConfig from taskConfig state: %v
• failed to reattach to executor: %v
• failed to launch command with executor: %v
• executor: error waiting on process: %v

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