eclipse-vertx/vert.x · error · FileSystemException

Failed to read ${p}

Error message

Failed to read ${p}

What it means

Wrapped error in readDirInternal: listing the directory's files (File.listFiles with or without a filter) or resolving canonical paths threw an IOException. The message names the read operation and the raw path; the concrete cause is attached. Note listFiles returning null (unreadable dir) can also surface as an NPE/IO failure here.

Source

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

                }
              };
            } else {
              fnFilter = null;
            }
            File[] files;
            if (fnFilter == null) {
              files = file.listFiles();
            } else {
              files = file.listFiles(fnFilter);
            }
            List<String> ret = new ArrayList<>(files.length);
            for (File f : files) {
              ret.add(f.getCanonicalPath());
            }
            return ret;
          }
        } catch (IOException e) {
          throw new FileSystemException(getFolderAccessErrorMessage("read", p), e);
        }
      }
    };
  }

  private BlockingAction<Buffer> readFileInternal(String path) {
    Objects.requireNonNull(path);
    return new BlockingAction<Buffer>() {
      public Buffer perform() {
        try {
          Path target = resolveFile(path).toPath();
          try (FileChannel fc = FileChannel.open(target, StandardOpenOption.READ)) {
            long size = fc.size();
            if (size > (long) Integer.MAX_VALUE) {
              // Throwing OOM as Files#readAllLines would in this case
              throw new OutOfMemoryError("File is too big");
            }
            int len = (int) size;

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Check the cause chain for the underlying I/O problem
2. Verify the directory is readable and not a special filesystem entry
3. Handle a null/empty listing gracefully

Example fix

// before (permission denied on /secure)
vertx.fileSystem().readDir("/secure");
// after
chmod o+rx /secure  # grant read/execute to the process user
vertx.fileSystem().readDir("/secure");

File dir = new File(path);
if (!dir.canRead() || !dir.canExecute()) {
  throw new IllegalStateException("No read access to directory: " + path);
}

try {
  fs.readDir(path);
} catch (FileSystemException e) {
  Throwable cause = e.getCause();
  if (cause instanceof IOException) {
    // inspect cause, retry once on transient NFS/IO errors
  }
}

When it happens

Trigger: Calling FileSystem.readDir(path) when the OS refuses or interrupts directory access — permission issues, I/O errors, or failure to canonicalize paths of entries.

Common situations: Directory readable via metadata but unreadable in practice (NFS stale handles, removed while iterating, SELinux/AppArmor denial), or the process losing read permission between the exists() check and the listing.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

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