apache/druid · error · org.apache.druid.java.util.common.ISE

Unable to fetch the file list from the path

Error message

Unable to fetch the file list from the path [%s]

What it means

After confirming the path is a directory, listDir calls File.listFiles(); the JDK returns null (not an empty array) when an I/O error occurs, e.g. a permission problem or the directory disappearing concurrently. Druid converts that null into an IllegalStateException because it cannot distinguish 'empty' from 'failed'.

Solutions

1. Check and fix filesystem permissions (read+execute on the directory) for the Druid process user
2. Re-run the operation; if a concurrent deleter is involved, serialize or skip deleted dirs
3. If persistent, inspect mount health (NFS/overlay) and ensure the directory is not being removed concurrently

Example fix

// before
Iterator<String> it = connector.listDir("logs");
// after
try {
  Iterator<String> it = connector.listDir("logs");
} catch (IllegalStateException e) {
  // check permissions on the logs directory for the druid user
}

File dir = new File(basePath, dirName);
if (!dir.canRead() || !dir.isDirectory()) {
  throw new IllegalStateException("cannot read directory " + dirName);
}

try { connector.listDir(dir); } catch (IllegalStateException e) { // treat as I/O failure: check perms, retry or fail }

When it happens

Trigger: listDir(dirName) where the directory exists and is a directory, but File.listFiles() returns null — typically because the process lacks read permission on the directory, or the directory was deleted between the isDirectory() check and listFiles().

Common situations: Druid running as a user without read access to the segment/task log directories; NFS or HDFS mounts dropping the directory mid-listing; concurrent cleanup job deleting intermediate task directories while a lookup runs.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

• Cannot create directory
• Cannot create tempDir
• Cannot delete temp file
• Cannot list contents of
• Cannot list directory

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/storage/local/LocalFileStorageConnector.java:165

  public void deleteRecursively(String dirName) throws IOException
  {
    log.debug("Deleting directory at path: [%s]", dirName);
    FileUtils.deleteDirectory(fileWithBasePath(dirName));
  }

  @Override
  public Iterator<String> listDir(String dirName)
  {
    File directory = fileWithBasePath(dirName);
    if (!directory.exists()) {
      throw new IAE("No directory exists on path [%s]", dirName);
    }
    if (!directory.isDirectory()) {
      throw new IAE("Cannot list contents of [%s] since it is not a directory", dirName);
    }
    File[] files = directory.listFiles();
    if (files == null) {
      throw new ISE("Unable to fetch the file list from the path [%s]", dirName);
    }
    return Arrays.stream(files).map(File::getName).iterator();
  }

  public File getBasePath()
  {
    return basePath;
  }

  private File fileWithBasePath(String path)
  {
    return new File(basePath, path);
  }

}

View on GitHub (pinned to 9b90983fd2)