hashicorp/nomad · error

binary %q could not be found

Error message

binary %q could not be found

What it means

lookupBin resolves a task binary: if the path is not absolute it searches $PATH with exec.LookPath. When LookPath cannot find an executable with that name anywhere on PATH, the executor returns 'binary %q could not be found'. This is raised from Launch, so the task fails to start.

Source

Thrown at drivers/shared/executor/executor.go:769

	root := filepath.Join(taskDir, bin)
	if _, err := os.Stat(root); err == nil {
		return root, nil
	}

	// when checking host paths, check with Stat first if path is absolute
	// as exec.LookPath only considers files already marked as executable
	// and only consider this for absolute paths to avoid depending on
	// current directory of nomad which may cause unexpected behavior
	if _, err := os.Stat(bin); err == nil && filepath.IsAbs(bin) {
		return bin, nil
	}

	// Check the $PATH
	if host, err := exec.LookPath(bin); err == nil {
		return host, nil
	}

	return "", fmt.Errorf("binary %q could not be found", bin)
}

// makeExecutable makes the given file executable for root,group,others.
func makeExecutable(binPath string) error {
	if runtime.GOOS == "windows" {
		return nil
	}

	fi, err := os.Stat(binPath)
	if err != nil {
		if os.IsNotExist(err) {
			return fmt.Errorf("binary %q does not exist", binPath)
		}
		return fmt.Errorf("specified binary is invalid: %v", err)
	}

	// If it is not executable, make it so.
	perm := fi.Mode().Perm()

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Use an absolute path to the binary in the task command
2. Install the binary or add its directory to the Nomad client's PATH environment
3. If Nomad runs as a service, extend the service unit's PATH (Environment=PATH=...)
4. Verify on the client host with 'which <binary>' as the same user Nomad runs as

Example fix

// before
driver = "raw_exec"
config { command = "mytool" } // relies on PATH
// after
config { command = "/usr/local/bin/mytool" }

bin := cfg.Command
if !filepath.IsAbs(bin) {
    if _, err := exec.LookPath(bin); err != nil {
        return fmt.Errorf("binary %q not on PATH of Nomad client: %w", bin, err)
    }
}

func binaryResolvable(bin string) bool {
    if filepath.IsAbs(bin) {
        _, err := os.Stat(bin)
        return err == nil
    }
    _, err := exec.LookPath(bin)
    return err == nil
}

if err := client.Launch(...); err != nil {
    if strings.Contains(err.Error(), "could not be found") {
        return fmt.Errorf("install binary or use absolute path: %w", err)
    }
    return err
}

When it happens

Trigger: Launching a task whose driver command (e.g. raw_exec/exec driver) names a binary that is not absolute and not present on any PATH directory; PATH differs between the Nomad client environment and the task environment.

Common situations: Binary installed only in a user-specific directory not on the client's PATH; typo in the binary name; systemd service running Nomad with a minimal PATH (e.g. /usr/bin:/bin) lacking /usr/local/bin; image or host missing the expected tool.

Related errors

• binary %q does not exist
• command is not present
• path cannot contain template delimiters or parenthesis
• not a terminal
• no exec command is configured

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