hashicorp/nomad · error

failed to launch command with executor: %v

Error message

failed to launch command with executor: %v

What it means

StartTask builds the executor command (with isolation settings, capabilities, mounts) and calls exec.Launch to run the user process under the executor. Any failure from Launch — the command not found, chroot/isolation setup errors, cgroup creation failure — is wrapped as this error.

Source

Thrown at drivers/exec/driver.go:546

		User:             user,
		ResourceLimits:   true,
		NoPivotRoot:      d.config.NoPivotRoot,
		Resources:        cfg.Resources,
		TaskDir:          cfg.TaskDir().Dir,
		WorkDir:          driverConfig.WorkDir,
		StdoutPath:       cfg.StdoutPath,
		StderrPath:       cfg.StderrPath,
		Mounts:           cfg.Mounts,
		Devices:          cfg.Devices,
		NetworkIsolation: cfg.NetworkIsolation,
		ModePID:          executor.IsolationMode(d.config.DefaultModePID, driverConfig.ModePID),
		ModeIPC:          executor.IsolationMode(d.config.DefaultModeIPC, driverConfig.ModeIPC),
		Capabilities:     caps,
	}

	ps, err := exec.Launch(execCmd)
	if err != nil {
		return nil, nil, fmt.Errorf("failed to launch command with executor: %v", err)
	}

	h := &taskHandle{
		exec:         exec,
		pid:          ps.Pid,
		pluginClient: pluginClient,
		taskConfig:   cfg,
		procState:    drivers.TaskStateRunning,
		startedAt:    time.Now().Round(time.Millisecond),
		logger:       d.logger,
	}

	driverState := TaskState{
		ReattachConfig: pstructs.ReattachConfigFromGoPlugin(pluginClient.ReattachConfig()),
		Pid:            ps.Pid,
		TaskConfig:     cfg,
		StartedAt:      h.startedAt,
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Confirm the command exists inside the chroot; add required paths via the task's 'mount' blocks or use absolute paths.
2. Run 'nomad alloc status <id>' and client logs for the executor's underlying error.
3. Verify cgroups are mounted and writable (both v1 and v2 layouts per OS).
4. Ensure the binary is statically linked or its libraries are available in the chroot (e.g., ldd the binary).
5. Check the requested capabilities match what the client's allow_caps permits.

Example fix

// before
config {
  command = "/opt/app/server" // not in chroot
}
// after
config {
  command = "/usr/local/bin/server"
  mounts = [{ host_path = "/opt/app", task_path = "/opt/app" }]
}

// verify the command exists and is executable in the chroot before launch
p := filepath.Join(chrootDir, command)
if fi, err := os.Stat(p); err != nil || fi.IsDir() || fi.Mode()&0o111 == 0 {
    return fmt.Errorf("command %s missing or not executable in chroot", command)
}

When it happens

Trigger: exec.Launch(execCmd) returns error: task command binary missing inside the chroot, isolation (chroot/cgroups) setup failed, capabilities cannot be applied, or the user cannot exec the command.

Common situations: command path not present in the chroot (not in the mounted whitelist); missing shared libraries in chroot; cgroups v1/v2 misconfiguration; cap_add beyond allowed set rejected at exec time.

Related errors

• failed to launch command with executor: %v
• Failed to mount shared directory for task: %w
• failed to start plugin: %v
• default_pid_mode must be %q or %q, got %q
• default_ipc_mode must be %q or %q, got %q

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