{"record":{"id":"827e1f73a62e5ee6","repo":"apache/hadoop","slug":"hadoop-home-directory-does-not-exist","errorCode":null,"errorMessage":"Hadoop home directory {} does not exist","messagePattern":"Hadoop home directory (.+?) does not exist","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/util/Shell.java","lineNumber":544,"sourceCode":"    }\n    while (home.endsWith(\"\\\"\")) {\n      home = home.substring(0, home.length() - 1);\n    }\n\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   */","sourceCodeStart":526,"sourceCodeEnd":562,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/util/Shell.java#L526-L562","documentation":"Shell.checkHadoopHome() validates the Hadoop installation directory resolved from the HADOOP_HOME environment variable or the hadoop.home.dir system property. If that path does not exist on the local filesystem, it throws FileNotFoundException during Shell's static initialization, because Hadoop cannot anchor the location of its binaries and scripts (e.g. winutils.exe on Windows). This error almost always means the environment, not the code, is wrong.","triggerScenarios":"Running any code path that touches org.apache.hadoop.util.Shell (ShellCommandExecutor, Shell.WINDOWS checks, local FileSystem setup on Windows, Shell.getHadoopHome()) while HADOOP_HOME points to a directory that is absent on this machine; or System.setProperty(\"hadoop.home.dir\", path) with a stale/typo'd path before the first Shell call.","commonSituations":"Typo in HADOOP_HOME in .bashrc / Windows env vars; Hadoop tarball upgraded or moved and the old path left behind; CI or Docker images that export HADOOP_HOME before extracting the distribution; Windows dev boxes pointing at a deleted winutils folder.","solutions":["Print the active value and test it: echo $HADOOP_HOME (or echo %HADOOP_HOME%) then ls that path — it must exist","Fix HADOOP_HOME (or the hadoop.home.dir system property) to the extracted distribution root: the directory that actually contains bin/ and etc/","In Dockerfiles, set ENV HADOOP_HOME only after COPY/extract of the distribution into that exact path","If the install location is unknown, unset HADOOP_HOME so Shell falls back to resolving home from the hadoop-common jar location on the classpath"],"exampleFix":"// before\nexport HADOOP_HOME=/opt/haddoop-3.3.6   # typo: directory does not exist\n\n// after\nexport HADOOP_HOME=/opt/hadoop-3.3.6\nls \"$HADOOP_HOME/bin\" \"$HADOOP_HOME/etc\"   # sanity check: both must resolve","handlingStrategy":"validation","validationCode":"String home = System.getenv(\"HADOOP_HOME\");\nif (home == null) {\n  home = System.getProperty(\"hadoop.home.dir\");\n}\nif (home == null || !new File(home).isAbsolute() || !new File(home).isDirectory()) {\n  throw new IllegalStateException(\"Invalid HADOOP_HOME (must be an existing absolute directory): \" + home);\n}\n// safe to trigger Shell / FileSystem APIs now","typeGuard":null,"tryCatchPattern":"try { Shell.getHadoopHome(); } catch (FileNotFoundException e) { /* re-read env, prompt operator, abort startup */ }","preventionTips":["Set HADOOP_HOME in one place (entrypoint script / image ENV) right after the distribution is extracted at that exact path","Add a CI smoke step: test -d \"$HADOOP_HOME/bin\" before running Hadoop client tests","Fail fast at application start with a clear message instead of letting Shell's static init throw deep in a call stack","Keep hadoop.home.dir system property and HADOOP_HOME env var consistent — never set only one to a different path"],"tags":["hadoop","shell","hadoop-home","environment-variable","filenotfound"],"backgroundTag":"invalid-hadoop-home","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}