{"record":{"id":"2ea4249730e76ff3","repo":"apache/druid","slug":"failed-to-access-hdfs","errorCode":null,"errorMessage":"Failed to access hdfs.","messagePattern":"Failed to access hdfs\\.","errorType":"exception","errorClass":"ISE","httpStatus":null,"severity":"critical","filePath":"extensions-core/hdfs-storage/src/main/java/org/apache/druid/storage/hdfs/HdfsStorageAvailabilityChecker.java","lineNumber":59,"sourceCode":"  public HdfsStorageAvailabilityChecker(@Hdfs Configuration hadoopConf)\n  {\n    this.hadoopConf = hadoopConf;\n  }\n\n  @LifecycleStart\n  public void checkHdfsAvailability()\n  {\n    try {\n      // If cache is enabled, need to check the FileSystem object by access hdfs because FileSystem object will be used later, like in push stage.\n      // If FileSystem is invalid, the peon task should stop immediately.\n      boolean disableCache = hadoopConf.getBoolean(\"fs.hdfs.impl.disable.cache\", false);\n      if (!disableCache) {\n        FileSystem fs = FileSystem.get(hadoopConf);\n        fs.exists(new Path(\"/\"));\n      }\n    }\n    catch (IOException ex) {\n      throw new ISE(ex, \"Failed to access hdfs.\");\n    }\n  }\n\n  @LifecycleStop\n  public void stop()\n  {\n    //noop\n  }\n}\n","sourceCodeStart":41,"sourceCodeEnd":69,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/extensions-core/hdfs-storage/src/main/java/org/apache/druid/storage/hdfs/HdfsStorageAvailabilityChecker.java#L41-L69","documentation":"HdfsStorageAvailabilityChecker.checkHdfsAvailability() performs a cheap probe — FileSystem.get(conf) then fs.exists(new Path(\"/\")) — to verify HDFS is reachable at startup. Any IOException from this probe is wrapped in an ISE with the generic message 'Failed to access hdfs.', with the underlying exception attached as the cause.","triggerScenarios":"checkHdfsAvailability() runs when caching is not disabled and the HDFS client throws an IOException on get() or exists(\"/\") — typically NameNode unreachable, misconfigured fs.defaultFS, or missing core-site.xml.","commonSituations":"NameNode down or firewalled from the Druid node; HADOOP_CONF_DIR not set so fs.defaultFS defaults to file:/// or an unknown host; wrong cluster config after a NameNode HA failover; DNS resolution failure for the NameNode.","solutions":["Check NameNode availability and network connectivity (hdfs dfs -ls / on the Druid node)","Verify Hadoop config (core-site.xml, hdfs-site.xml) is on the Druid classpath and HADOOP_CONF_DIR is set","Confirm fs.defaultFS points to the correct cluster (ha:// nameservice if HA)","Inspect the IOException cause in the stack trace for the specific host/port that failed"],"exampleFix":"// before\n// druid startup without Hadoop conf\necho $HADOOP_CONF_DIR  # empty\n// after\nexport HADOOP_CONF_DIR=/etc/hadoop/conf\n# restart Druid node","handlingStrategy":"try-catch","validationCode":"// before starting Druid, verify from the same host/user:\n// hdfs dfs -ls /  (uses identical core-site.xml/hdfs-site.xml)","typeGuard":"null","tryCatchPattern":"try {\n  checker.start();\n} catch (ISE e) {\n  Throwable cause = e.getCause();\n  log.error(\"HDFS probe failed: {}\", cause == null ? e : cause.getMessage(), cause);\n  throw e; // fail fast; check NameNode and HADOOP_CONF_DIR\n}","preventionTips":["Set HADOOP_CONF_DIR and ship core-site.xml/hdfs-site.xml with Druid","Run a CLI HDFS smoke test on every node before service start","Monitor NameNode availability and DNS for the NameNode hosts"],"tags":["hdfs","connectivity","startup-check","io"],"backgroundTag":"http-request-failed","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}