eclipse-vertx/vert.x · error · FileSystemException

Cannot read directory ${file}. It's not a directory

Error message

Cannot read directory ${file}. It's not a directory

What it means

Filesystem check in readDirInternal: the resolved path exists but is a regular file, not a directory, so its entries cannot be listed. The offending path is included in the message to distinguish this from the does-not-exist case.

Source

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

      }
    };
  }

  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();
            } else {
              files = file.listFiles(fnFilter);
            }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Point readDir at an actual directory
2. Use readFile/fs.props if a file was intended

Example fix

// before
vertx.fileSystem().readDir("/etc/app/config.json");
// after
vertx.fileSystem().readDir("/etc/app");

io.vertx.core.file.FileProps props = vertx.fileSystem().propsBlocking(path);
if (props == null || !props.isDirectory()) {
  throw new IllegalArgumentException("Not a directory: " + path);
}

try {
  fs.readDir(path);
} catch (FileSystemException e) {
  logger.warn("{} is not a directory", path);
}

When it happens

Trigger: Calling FileSystem.readDir(path) with a path that points to an existing file instead of a directory.

Common situations: Config pointing at a file where a directory is expected (e.g. a cert file where a certs directory was expected), or a path that changed type between environments.

Related errors

• Failed to delete ${path}
• Failed to create ${path}
• Cannot read directory ${file}. Does not exist
• 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/7cec4841ee62d494. Report an issue: GitHub.