{"record":{"id":"b49b50db913f5b17","repo":"hashicorp/nomad","slug":"binary-q-could-not-be-found","errorCode":null,"errorMessage":"binary %q could not be found","messagePattern":"binary %q could not be found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/shared/executor/executor.go","lineNumber":769,"sourceCode":"\troot := filepath.Join(taskDir, bin)\n\tif _, err := os.Stat(root); err == nil {\n\t\treturn root, nil\n\t}\n\n\t// when checking host paths, check with Stat first if path is absolute\n\t// as exec.LookPath only considers files already marked as executable\n\t// and only consider this for absolute paths to avoid depending on\n\t// current directory of nomad which may cause unexpected behavior\n\tif _, err := os.Stat(bin); err == nil && filepath.IsAbs(bin) {\n\t\treturn bin, nil\n\t}\n\n\t// Check the $PATH\n\tif host, err := exec.LookPath(bin); err == nil {\n\t\treturn host, nil\n\t}\n\n\treturn \"\", fmt.Errorf(\"binary %q could not be found\", bin)\n}\n\n// makeExecutable makes the given file executable for root,group,others.\nfunc makeExecutable(binPath string) error {\n\tif runtime.GOOS == \"windows\" {\n\t\treturn nil\n\t}\n\n\tfi, err := os.Stat(binPath)\n\tif err != nil {\n\t\tif os.IsNotExist(err) {\n\t\t\treturn fmt.Errorf(\"binary %q does not exist\", binPath)\n\t\t}\n\t\treturn fmt.Errorf(\"specified binary is invalid: %v\", err)\n\t}\n\n\t// If it is not executable, make it so.\n\tperm := fi.Mode().Perm()","sourceCodeStart":751,"sourceCodeEnd":787,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/shared/executor/executor.go#L751-L787","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use an absolute path to the binary in the task command","Install the binary or add its directory to the Nomad client's PATH environment","If Nomad runs as a service, extend the service unit's PATH (Environment=PATH=...)","Verify on the client host with 'which <binary>' as the same user Nomad runs as"],"exampleFix":"// before\ndriver = \"raw_exec\"\nconfig { command = \"mytool\" } // relies on PATH\n// after\nconfig { command = \"/usr/local/bin/mytool\" }","handlingStrategy":"validation","validationCode":"bin := cfg.Command\nif !filepath.IsAbs(bin) {\n    if _, err := exec.LookPath(bin); err != nil {\n        return fmt.Errorf(\"binary %q not on PATH of Nomad client: %w\", bin, err)\n    }\n}","typeGuard":"func binaryResolvable(bin string) bool {\n    if filepath.IsAbs(bin) {\n        _, err := os.Stat(bin)\n        return err == nil\n    }\n    _, err := exec.LookPath(bin)\n    return err == nil\n}","tryCatchPattern":"if err := client.Launch(...); err != nil {\n    if strings.Contains(err.Error(), \"could not be found\") {\n        return fmt.Errorf(\"install binary or use absolute path: %w\", err)\n    }\n    return err\n}","preventionTips":["Prefer absolute binary paths in task configs","Check 'which <bin>' on the client host as the same user Nomad runs as","If Nomad runs under systemd, extend the unit's PATH explicitly","Distribute binaries via artifact blocks instead of relying on host PATH"],"tags":["exec","path","launch"],"backgroundTag":"binary-not-found-on-path","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}