apache/hadoop · error · FileNotFoundException

Could not locate Hadoop executable: {}

Error message

Could not locate Hadoop executable: {}

What it means

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.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/util/Shell.java:671

   * @return path to the binary
   * @throws FileNotFoundException if the executable was not found/valid
   */
  static File getQualifiedBinInner(File hadoopHomeDir, String executable)
      throws FileNotFoundException {
    String binDirText = "Hadoop bin directory ";
    File bin = new File(hadoopHomeDir, "bin");
    if (!bin.exists()) {
      throw new FileNotFoundException(addOsText(binDirText + E_DOES_NOT_EXIST
          + ": " + bin));
    }
    if (!bin.isDirectory()) {
      throw new FileNotFoundException(addOsText(binDirText + E_NOT_DIRECTORY
          + ": " + bin));
    }

    File exeFile = new File(bin, executable);
    if (!exeFile.exists()) {
      throw new FileNotFoundException(
          addOsText(E_NO_EXECUTABLE + ": " + exeFile));
    }
    if (!exeFile.isFile()) {
      throw new FileNotFoundException(
          addOsText(E_NOT_EXECUTABLE_FILE + ": " + exeFile));
    }
    try {
      return exeFile.getCanonicalFile();
    } catch (IOException e) {
      // this isn't going to happen, because of all the upfront checks.
      // so if it does, it gets converted to a FNFE and rethrown
      throw fileNotFoundException(e.toString(), e);
    }
  }

  /**
   *  Fully qualify the path to a binary that should be in a known hadoop
   *  bin location. This is primarily useful for disambiguating call-outs

View on GitHub (pinned to 2add963021)

Solutions

1. Confirm what is actually there: dir %HADOOP_HOME%\bin (or ls "$HADOOP_HOME/bin")
2. Download a winutils build matching your exact hadoop-common version and copy winutils.exe and hadoop.dll into %HADOOP_HOME%\bin
3. Align versions: the hadoop.version in your pom/gradle must equal the winutils build, otherwise replace one of them
4. If native Windows support is not required, run the workload in WSL or a Linux container to sidestep winutils entirely

Example fix

<!-- before: pom uses hadoop 3.3.6, HADOOP_HOME\bin has winutils.exe from 3.1.0 or nothing -->

<!-- after -->
:: fetch matching build and install
xcopy cdarwin-winutils-3.3.6\hadoop-3.3.6\bin\* %HADOOP_HOME%\bin\
dir %HADOOP_HOME%\bin\winutils.exe   :: now resolves

String exe = Shell.WINDOWS ? "winutils.exe" : "hadoop";
File f = new File(new File(new File(System.getenv("HADOOP_HOME")), "bin"), exe);
if (!f.isFile()) {
  throw new IllegalStateException("Hadoop executable missing: " + f
      + " — install a version-matched (winutils) build");
}

try { Shell.getQualifiedBin("winutils.exe"); } catch (FileNotFoundException e) { throw new IllegalStateException("Install winutils.exe matching hadoop-common " + VersionInfo.getVersion(), e); }

When it happens

Trigger: 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/.

Common situations: 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.

Related errors

• Error while running command to get file permissions : " + St
• Hadoop bin directory does not exist: {}
• Not an executable file: {}
• Hadoop home directory {} does not exist
• Hadoop home directory {} is not a directory.

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/3658c46497c0278c. Report an issue: GitHub.