apache/druid · critical · ISE

Failed to access hdfs.

Error message

Failed to access hdfs.

What it means

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.

Source

Thrown at extensions-core/hdfs-storage/src/main/java/org/apache/druid/storage/hdfs/HdfsStorageAvailabilityChecker.java:59

  public HdfsStorageAvailabilityChecker(@Hdfs Configuration hadoopConf)
  {
    this.hadoopConf = hadoopConf;
  }

  @LifecycleStart
  public void checkHdfsAvailability()
  {
    try {
      // If cache is enabled, need to check the FileSystem object by access hdfs because FileSystem object will be used later, like in push stage.
      // If FileSystem is invalid, the peon task should stop immediately.
      boolean disableCache = hadoopConf.getBoolean("fs.hdfs.impl.disable.cache", false);
      if (!disableCache) {
        FileSystem fs = FileSystem.get(hadoopConf);
        fs.exists(new Path("/"));
      }
    }
    catch (IOException ex) {
      throw new ISE(ex, "Failed to access hdfs.");
    }
  }

  @LifecycleStop
  public void stop()
  {
    //noop
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Check NameNode availability and network connectivity (hdfs dfs -ls / on the Druid node)
2. Verify Hadoop config (core-site.xml, hdfs-site.xml) is on the Druid classpath and HADOOP_CONF_DIR is set
3. Confirm fs.defaultFS points to the correct cluster (ha:// nameservice if HA)
4. Inspect the IOException cause in the stack trace for the specific host/port that failed

Example fix

// before
// druid startup without Hadoop conf
echo $HADOOP_CONF_DIR  # empty
// after
export HADOOP_CONF_DIR=/etc/hadoop/conf
# restart Druid node

// before starting Druid, verify from the same host/user:
// hdfs dfs -ls /  (uses identical core-site.xml/hdfs-site.xml)

null

try {
  checker.start();
} catch (ISE e) {
  Throwable cause = e.getCause();
  log.error("HDFS probe failed: {}", cause == null ? e : cause.getMessage(), cause);
  throw e; // fail fast; check NameNode and HADOOP_CONF_DIR
}

When it happens

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

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

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• Failed to rename temp file [%s] and final segment path [%s]
• Input stream is null
• Failed to fetch google cloud storage object from bucket [%s]
• Failed to fetch google cloud storage object from bucket [%s]
• Failed to stream logs from: %s

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/2ea4249730e76ff3. Report an issue: GitHub.