{"record":{"id":"7a98444943ee727f","repo":"apache/hadoop","slug":"hadoop-home-directory-is-not-a-directory","errorCode":null,"errorMessage":"Hadoop home directory {} is not a directory.","messagePattern":"Hadoop home directory (.+?) is not a directory\\.","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/util/Shell.java","lineNumber":548,"sourceCode":"\n    // after stripping any quotes, check for home dir being non-empty\n    if (home.isEmpty()) {\n      throw new FileNotFoundException(E_HADOOP_PROPS_EMPTY);\n    }\n\n    // check that the hadoop home dir value\n    // is an absolute reference to a directory\n    File homedir = new File(home);\n    if (!homedir.isAbsolute()) {\n      throw new FileNotFoundException(\"Hadoop home directory \" + homedir\n          + \" \" + E_IS_RELATIVE);\n    }\n    if (!homedir.exists()) {\n      throw new FileNotFoundException(\"Hadoop home directory \" + homedir\n          + \" \" + E_DOES_NOT_EXIST);\n    }\n    if (!homedir.isDirectory()) {\n      throw new FileNotFoundException(\"Hadoop home directory \" + homedir\n          + \" \"+ E_NOT_DIRECTORY);\n    }\n    return homedir;\n  }\n\n  /**\n   * The Hadoop home directory.\n   */\n  private static final File HADOOP_HOME_FILE;\n\n  /**\n   * Rethrowable cause for the failure to determine the hadoop\n   * home directory\n   */\n  private static final IOException HADOOP_HOME_DIR_FAILURE_CAUSE;\n\n  static {\n    File home;","sourceCodeStart":530,"sourceCodeEnd":566,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/util/Shell.java#L530-L566","documentation":"Shell.checkHadoopHome() validates the resolved Hadoop home directory (HADOOP_HOME env var or hadoop.home.dir system property). The path exists but java.io.File.isDirectory() is false — it is a regular file — so it cannot contain bin/ and Shell throws FileNotFoundException. The installation reference is shape-wrong, not merely missing.","triggerScenarios":"HADOOP_HOME or hadoop.home.dir names a file, e.g. the hadoop-3.3.6.tar.gz archive itself, a metadata file, or a symlink chain that ends at a file; then any Shell-dependent API (Windows file ops, ShellCommandExecutor, winutils lookup) triggers the check.","commonSituations":"Pointing HADOOP_HOME at the downloaded tarball instead of the extracted directory; a Docker COPY that placed a file at the path the env var names; symlink targets replaced by files during upgrades.","solutions":["Inspect the entry: ls -ld \"$HADOOP_HOME\" — the mode must start with 'd'; on Windows use dir %HADOOP_HOME% and check for <DIR>","If it is a file, extract the distribution and set HADOOP_HOME to the resulting directory (containing bin/)","Fix the hadoop.home.dir system property the same way if it is the source of the value","Replace any symlink at that path with a real directory or a link that resolves to one"],"exampleFix":"// before\nexport HADOOP_HOME=/opt/hadoop-3.3.6.tar.gz   # the archive, a file\n\n// after\ntar -xzf /opt/hadoop-3.3.6.tar.gz -C /opt/\nexport HADOOP_HOME=/opt/hadoop-3.3.6            # the extracted directory","handlingStrategy":"validation","validationCode":"File home = new File(System.getenv().getOrDefault(\"HADOOP_HOME\",\n    System.getProperty(\"hadoop.home.dir\", \"\")));\nif (!home.isDirectory()) { // exists AND is a directory\n  throw new IllegalStateException(\"HADOOP_HOME must be a directory, got: \" + home);\n}","typeGuard":null,"tryCatchPattern":"try { Shell.getHadoopHome(); } catch (FileNotFoundException e) { log.error(\"Fix HADOOP_HOME: not a directory: {}\", e.getMessage()); throw e; }","preventionTips":["Provision HADOOP_HOME exclusively from an extracted archive so it is a directory by construction","Add ls -ld $HADOOP_HOME to environment bootstrap scripts to assert the 'd' mode","In Docker, COPY the extracted tree (not the tarball) to the ENV-declared path"],"tags":["hadoop","shell","hadoop-home","filenotfound","configuration"],"backgroundTag":"invalid-hadoop-home","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}