hashicorp/nomad · error

file %s not found under path

Error message

file %s not found under path

What it means

lookupTaskBin exhausted all search directories (task dir plus configured lookup paths) without finding the bare binary name, so it fails with this message. It is the final 'binary not found anywhere in the task environment' error after PATH-style lookups fail.

Source

Thrown at drivers/shared/executor/executor_linux_cgo.go:1037

	// root. Similar to the stdlib's exec.LookPath except:
	//   - uses a restricted lookup PATH rather than the agent process's PATH env var.
	//   - does not require that the file is already executable (this will be ensured
	//     by the caller)
	//   - does not prevent using relative path as added to exec.LookPath in go1.19
	//     (this gets fixed-up in the caller)

	// This is a fake PATH so that we're not using the agent's PATH
	restrictedPaths := []string{"/usr/local/bin", "/usr/bin", "/bin"}

	for _, dir := range restrictedPaths {
		pathDir := filepath.Join(command.TaskDir, dir)
		taskPath, hostPath, err = getPathInTaskDir(command.TaskDir, pathDir, bin)
		if err == nil {
			return taskPath, hostPath, nil
		}
	}

	return "", "", fmt.Errorf("file %s not found under path", bin)
}

// getPathInTaskDir searches for the binary in the task directory and nested
// search directory. It returns the absolute path rooted inside the container
// and the absolute path on the host.
func getPathInTaskDir(taskDir, searchDir, bin string) (string, string, error) {

	hostPath := filepath.Join(searchDir, bin)
	err := filepathIsRegular(hostPath)
	if err != nil {
		return "", "", err
	}

	// Find the path relative to the task directory
	rel, err := filepath.Rel(taskDir, hostPath)
	if rel == "" || err != nil {
		return "", "", fmt.Errorf(
			"failed to determine relative path base=%q target=%q: %v",

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Confirm where the binary actually is in the allocation dir and set command to that relative path
2. Fix artifact destination so the binary lands in a searched directory (task dir root)
3. Correct the binary name/case in the job spec
4. If using env-provided search dirs, ensure the required dir is included before launch

Example fix

// before
command = "app"   # app is actually in local/bin/app
// after
command = "local/bin/app"

// binary name with no slash must exist in task dir or a search dir
if !strings.Contains(task.Command, "/") {
    if _, err := os.Stat(filepath.Join(taskDir, task.Command)); err != nil {
        return fmt.Errorf("bare binary %q not in task dir", task.Command)
    }
}

if err != nil && strings.Contains(err.Error(), "file ") && strings.Contains(err.Error(), "not found under path") {
    return fmt.Errorf("binary lookup failed; verify artifacts and command name: %w", err)
}

When it happens

Trigger: Launch with a binary name containing no '/' where neither the task dir nor any search path directories contain an executable file named bin — all getPathInTaskDir attempts returned errors.

Common situations: command = "myapp" but the artifact put it under a subdirectory; forgot to download the binary at all; binary name typo or wrong case; PATH_DIR task env (NOMAD_TASK_PATH-style search dirs) not including the artifact destination.

Related errors

• file %s not found under path %s
• failed to determine relative path base=%q target=%q: %v
• path was not a regular file
• ErrCgroupMustBeSet
• user name must contain domain

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