{"record":{"id":"3658c46497c0278c","repo":"apache/hadoop","slug":"could-not-locate-hadoop-executable","errorCode":null,"errorMessage":"Could not locate Hadoop executable: {}","messagePattern":"Could not locate Hadoop executable: (.+?)","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/util/Shell.java","lineNumber":671,"sourceCode":"   * @return path to the binary\n   * @throws FileNotFoundException if the executable was not found/valid\n   */\n  static File getQualifiedBinInner(File hadoopHomeDir, String executable)\n      throws FileNotFoundException {\n    String binDirText = \"Hadoop bin directory \";\n    File bin = new File(hadoopHomeDir, \"bin\");\n    if (!bin.exists()) {\n      throw new FileNotFoundException(addOsText(binDirText + E_DOES_NOT_EXIST\n          + \": \" + bin));\n    }\n    if (!bin.isDirectory()) {\n      throw new FileNotFoundException(addOsText(binDirText + E_NOT_DIRECTORY\n          + \": \" + bin));\n    }\n\n    File exeFile = new File(bin, executable);\n    if (!exeFile.exists()) {\n      throw new FileNotFoundException(\n          addOsText(E_NO_EXECUTABLE + \": \" + exeFile));\n    }\n    if (!exeFile.isFile()) {\n      throw new FileNotFoundException(\n          addOsText(E_NOT_EXECUTABLE_FILE + \": \" + exeFile));\n    }\n    try {\n      return exeFile.getCanonicalFile();\n    } catch (IOException e) {\n      // this isn't going to happen, because of all the upfront checks.\n      // so if it does, it gets converted to a FNFE and rethrown\n      throw fileNotFoundException(e.toString(), e);\n    }\n  }\n\n  /**\n   *  Fully qualify the path to a binary that should be in a known hadoop\n   *  bin location. This is primarily useful for disambiguating call-outs","sourceCodeStart":653,"sourceCodeEnd":689,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/util/Shell.java#L653-L689","documentation":"Shell.getQualifiedBinInner() resolved ${hadoopHome}/bin/<executable> but the executable file itself does not exist, so it throws FileNotFoundException with E_NO_EXECUTABLE. On Windows the requested executable is nearly always winutils.exe, making this the classic 'Could not locate Hadoop executable: ...winutils.exe' failure raised by local FileSystem operations.","triggerScenarios":"Running a Hadoop client on Windows (RawLocalFileSystem, tmp dir creation, chmod/chown calls) when %HADOOP_HOME%\\bin lacks winutils.exe; also Shell.getQualifiedBin(\"hadoop\", ...) when the hadoop launcher script is absent from bin/.","commonSituations":"Using hadoop-common from Maven on Windows without installing a winutils distribution; winutils present but for a different point release; containers that mount bin/ without the native tool.","solutions":["Confirm what is actually there: dir %HADOOP_HOME%\\bin (or ls \"$HADOOP_HOME/bin\")","Download a winutils build matching your exact hadoop-common version and copy winutils.exe and hadoop.dll into %HADOOP_HOME%\\bin","Align versions: the hadoop.version in your pom/gradle must equal the winutils build, otherwise replace one of them","If native Windows support is not required, run the workload in WSL or a Linux container to sidestep winutils entirely"],"exampleFix":"<!-- before: pom uses hadoop 3.3.6, HADOOP_HOME\\bin has winutils.exe from 3.1.0 or nothing -->\n\n<!-- after -->\n:: fetch matching build and install\nxcopy cdarwin-winutils-3.3.6\\hadoop-3.3.6\\bin\\* %HADOOP_HOME%\\bin\\\ndir %HADOOP_HOME%\\bin\\winutils.exe   :: now resolves","handlingStrategy":"validation","validationCode":"String exe = Shell.WINDOWS ? \"winutils.exe\" : \"hadoop\";\nFile f = new File(new File(new File(System.getenv(\"HADOOP_HOME\")), \"bin\"), exe);\nif (!f.isFile()) {\n  throw new IllegalStateException(\"Hadoop executable missing: \" + f\n      + \" — install a version-matched (winutils) build\");\n}","typeGuard":null,"tryCatchPattern":"try { Shell.getQualifiedBin(\"winutils.exe\"); } catch (FileNotFoundException e) { throw new IllegalStateException(\"Install winutils.exe matching hadoop-common \" + VersionInfo.getVersion(), e); }","preventionTips":["Pin the winutils build number to the exact hadoop-common version in your build (hadoop.version property)","Automate provisioning: a setup script copies winutils.exe + hadoop.dll into HADOOP_HOME\\bin before tests run","On Windows CI, assert Files.isRegularFile(Path.of(home, \"bin\", \"winutils.exe\")) as a pre-flight check","Consider WSL/Linux containers for workloads that don't strictly need native Windows file ops"],"tags":["hadoop","windows","winutils","executable","filenotfound"],"backgroundTag":"missing-winutils","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}