hashicorp/nomad · error

failed to launch command with executor: %v

Error message

failed to launch command with executor: %v

What it means

After the executor is created, StartTask calls exec.Launch(execCmd) to actually start the java command under isolation. Any failure launching the process — bad binary path, setuid/user switching failure, resource limit setup, namespace/cgroup setup on Linux, invalid mounts/devices/capabilities — is wrapped with this message. The java command was fully configured at this point, so the error usually reflects isolation/environment problems rather than job config syntax.

Source

Thrown at drivers/java/driver.go:525

		Env:              cfg.EnvList(),
		User:             user,
		ResourceLimits:   true,
		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. Check the Nomad client debug log for the underlying Launch error (cgroup, mount, setuid) and address that root cause.
2. If running Nomad inside Docker, start the container with --privileged and proper mounts, or set driver java options to disable unsupported isolation (e.g. mode_pid/mode_ipc = "private" vs host defaults).
3. Verify the task user exists on the host (e.g. nobody) and Nomad has permission to switch users (root or CAP_SETUID).
4. Confirm the java binary path works and the alloc dir/stdout/stderr paths are writable; retry the allocation.

Example fix

// before (Nomad in Docker, namespace setup fails)
docker run net=text nomad agent -dev
// after
docker run --privileged -v /var/run/docker.sock:/var/run/docker.sock nomad agent -dev

// preflight the exec environment before Launch
if user != "" {
    if _, err := user2.Lookup(user); err != nil {
        return fmt.Errorf("task user %q does not exist on host: %w", user, err)
    }
}
if _, err := os.Stat(absPath); err != nil {
    return fmt.Errorf("java binary not executable at %s: %w", absPath, err)
}
if err := unix.Access(filepath.Dir(cfg.StdoutPath), unix.W_OK); err != nil {
    return fmt.Errorf("stdout/stderr path not writable: %w", err)
}

_, _, err := driver.StartTask(cfg)
if err != nil && strings.Contains(err.Error(), "failed to launch command with executor") {
    // inspect client debug logs for cgroup/namespace/setuid root cause, then retry
    return InspectClientAndRetry(fmt.Errorf("executor could not launch java process: %w", err))
}

When it happens

Trigger: Calling StartTask when exec.Launch fails: java binary path (absPath) unusable at exec time, task user (e.g. 'nobody') cannot be setuid'd, cgroups/namespace creation fails, chroot/mount setup fails, CapAdd beyond allowed caps, or stdout/stderr paths unwritable.

Common situations: Linux clients without proper cgroup setup or with seccomp/AppArmor restrictions; running Nomad in unprivileged Docker where isolation modes (ModePID/ModeIPC) are unsupported; caps_calculation passing but kernel denying capabilities at exec; task user missing on host; disk full preventing redirection of stdout/stderr files.

Related errors

• failed to launch command with executor: %v
• failed to reattach to executor: %v
• failed to create executor: %v
• executor: error waiting on process: %v
• ErrCgroupMustBeSet

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