eclipse-vertx/vert.x · error · FileSystemException

Cannot read directory ${file}. Does not exist

Error message

Cannot read directory ${file}. Does not exist

What it means

Wrapped error in readDirInternal: the directory listing operation threw an IOException before the explicit existence/isDirectory checks could produce a precise message. The raw path p is reported; the real cause (permissions, I/O error during listFiles) is in the cause chain.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/file/impl/FileSystemImpl.java:814

            + "' at " + parentDir;
          throw new FileSystemException(message, e);
        }
      }
    };
  }

  private BlockingAction<List<String>> readDirInternal(String path) {
    return readDirInternal(path, null);
  }

  private BlockingAction<List<String>> readDirInternal(String p, String filter) {
    Objects.requireNonNull(p);
    return new BlockingAction<List<String>>() {
      public List<String> perform() {
        try {
          File file = resolveFile(p);
          if (!file.exists()) {
            throw new FileSystemException("Cannot read directory " + file + ". Does not exist");
          }
          if (!file.isDirectory()) {
            throw new FileSystemException("Cannot read directory " + file + ". It's not a directory");
          } else {
            FilenameFilter fnFilter;
            if (filter != null) {
              Pattern fnPattern = Pattern.compile(filter);
              fnFilter = new FilenameFilter() {
                public boolean accept(File dir, String name) {
                  return fnPattern.matcher(name).matches();
                }
              };
            } else {
              fnFilter = null;
            }
            File[] files;
            if (fnFilter == null) {
              files = file.listFiles();

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Inspect the exception cause for the underlying I/O error
2. Verify the directory exists, is a directory, and is readable by the process

Example fix

// before
vertx.fileSystem().readDir("/data/conf").onSuccess(...);
// after
vertx.fileSystem().exists("/data/conf")
  .compose(exists -> exists ? vertx.fileSystem().readDir("/data/conf")
                             : vertx.fileSystem().mkdir("/data/conf"))
  .onSuccess(files -> ...);

if (!vertx.fileSystem().existsBlocking(dir)) {
  throw new IllegalArgumentException("Directory does not exist: " + dir);
}

try {
  fs.readDir(dir);
} catch (FileSystemException e) {
  logger.warn("Cannot read dir {}: {}", dir, e.getMessage());
  return List.of(); // or create the directory
}

When it happens

Trigger: Calling FileSystem.readDir(path) (any overload, with or without filter) with a path that does not exist on the filesystem.

Common situations: Typos in the directory path, assuming a working-directory-relative path resolves where the app actually runs, or a directory that a previous setup step failed to create.

Related errors

• Failed to delete ${path}
• Failed to create ${path}
• Cannot read directory ${file}. It's not a directory
• Failed to read ${p}
• Failed to chmod ${path}

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/f8c21c98be0e7dbc. Report an issue: GitHub.