hashicorp/nomad · critical

failed to create executor: %v

Error message

failed to create executor: %v

What it means

executor.CreateExecutor failed to launch the executor as a go-plugin subprocess (executor plugin binary + nomad config). The driver never got a working executor client, so the task cannot be started. Causes are typically missing plugin binary, bad d.nomadConfig, or handshake/fork failures.

Source

Thrown at drivers/rawexec/driver.go:429

	if err := d.Validate(*cfg); err != nil {
		return nil, nil, fmt.Errorf("failed driver config validation: %v", err)
	}

	d.logger.Info("starting task", "driver_cfg", hclog.Fmt("%+v", driverConfig))
	handle := drivers.NewTaskHandle(taskHandleVersion)
	handle.Config = cfg

	pluginLogFile := filepath.Join(cfg.TaskDir().Dir, "executor.out")
	executorConfig := &executor.ExecutorConfig{
		LogFile:  pluginLogFile,
		LogLevel: "debug",
		Compute:  d.compute,
	}

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

	execCmd := &executor.ExecCommand{
		Cmd:              driverConfig.Command,
		Args:             driverConfig.Args,
		Env:              d.buildEnvList(&driverConfig, cfg),
		User:             cfg.User,
		TaskDir:          cfg.TaskDir().Dir,
		WorkDir:          driverConfig.WorkDir,
		StdoutPath:       cfg.StdoutPath,
		StderrPath:       cfg.StderrPath,
		NetworkIsolation: cfg.NetworkIsolation,
		Resources:        cfg.Resources.Copy(),
		OverrideCgroupV2: driverConfig.OverrideCgroupV2,
		OverrideCgroupV1: driverConfig.OverrideCgroupV1,
		OOMScoreAdj:      int32(driverConfig.OOMScoreAdj),
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check agent logs immediately above this error for the go-plugin handshake detail
2. Verify the nomad binary/executor plugin is present and executable on the client and versions match
3. Confirm data_dir and plugin configuration are correct and writable by the nomad user
4. Check OS-level blockers: ulimits (nproc/nofile), SELinux/AppArmor, container seccomp profiles blocking clone/fork
5. Retry after freeing resources (pids/memory) if the host was exhausted

// preflight on client host
test -x $(which nomad) || echo "executor plugin binary missing"
ulimit -u; ulimit -n   # ensure pid/fd headroom
ls -ld <data_dir>     # writable by nomad user?

h, net, err := d.StartTask(cfg)
if err != nil && strings.Contains(err.Error(), "failed to create executor") {
  // transient resource issues can be retried once
  return retryStartTask(cfg, 1)
}

When it happens

Trigger: StartTask calls executor.CreateExecutor and the go-plugin spawn fails: nomad executor binary not found/unlaunchable, plugin handshake timeout, insufficient permissions, or invalid NomadConfig.

Common situations: .nomad data_dir or plugin dir misconfigured; fork/exec failures from cgroup/namespace restrictions in containers; host resource exhaustion (no fds/pids/memory); SELinux/AppArmor blocking plugin exec; version mismatch between client agent and executor plugin.

Related errors

• failed to reattach to executor: %v
• failed to build ReattachConfig from task state: %v
• executor: error waiting on process: %v
• executor Shutdown failed: %v
• plugin not found

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