eclipse-vertx/vert.x · error · FileSystemException

Failed to analyse ${path}

Error message

Failed to analyse ${path}

What it means

Thrown when FileSystem.props / propsBlocking (or lprops) fails: Vert.x reads BasicFileAttributes via Files.readAttributes and wraps any IOException into a FileSystemException using getFileAccessErrorMessage("analyse", path). It indicates the file metadata could not be obtained — usually because the path does not exist or is not accessible.

Source

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

  private BlockingAction<FileProps> lpropsInternal(String path) {
    return props(path, false);
  }

  private BlockingAction<FileProps> props(String path, boolean followLinks) {
    Objects.requireNonNull(path);
    return new BlockingAction<FileProps>() {
      public FileProps perform() {
        try {
          Path target = resolveFile(path).toPath();
          BasicFileAttributes attrs;
          if (followLinks) {
            attrs = Files.readAttributes(target, BasicFileAttributes.class);
          } else {
            attrs = Files.readAttributes(target, BasicFileAttributes.class, LinkOption.NOFOLLOW_LINKS);
          }
          return new FilePropsImpl(attrs);
        } catch (IOException e) {
          throw new FileSystemException(getFileAccessErrorMessage("analyse", path), e);
        }
      }
    };
  }

  private BlockingAction<Void> linkInternal(String link, String existing) {
    return link(link, existing, false);
  }

  private BlockingAction<Void> symlinkInternal(String link, String existing) {
    return link(link, existing, true);
  }

  private BlockingAction<Void> link(String link, String existing, boolean symbolic) {
    Objects.requireNonNull(link);
    Objects.requireNonNull(existing);
    return new BlockingAction<Void>() {
      public Void perform() {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Check existence first with exists(path) / existsBlocking(path) before props().
2. Use lprops (NOFOLLOW_LINKS) to inspect a broken symlink without following it.
3. Verify the path string and working directory (Vert.x resolves relative to vertx.cwd / cwd).
4. Read the nested IOException cause for the exact OS error (NOENT, ACCESS).

Example fix

// before
FileProps props = vertx.fileSystem().propsBlocking("/app/config.json"); // NoSuchFileException
// after
if (vertx.fileSystem().existsBlocking("/app/config.json")) {
  FileProps props = vertx.fileSystem().propsBlocking("/app/config.json");
}

boolean exists = vertx.fileSystem().existsBlocking(path);
if (!exists) throw new FileNotFoundException(path);

try { return vertx.fileSystem().propsBlocking(path); } catch (FileSystemException e) { log.warn("props unavailable for {}: {}", path, e.getCause()); return null; }

When it happens

Trigger: Calling vertx.fileSystem().props(path) or lprops(path, followLinks) on a missing path, an unreadable parent directory, or a broken symlink being followed.

Common situations: Checking properties of a config file with a wrong path; props on a symlink whose target was removed; permission-restricted directories in containers; NFS stale handles.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Failed to chmod ${path}
• Failed to crown ${path}
• Unable to link existing file '${existing}' to '${link}'
• Failed to read ${link}
• Failed to delete ${path}

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