eclipse-vertx/vert.x · error · FileSystemException

Failed to chmod ${path}

Error message

Failed to chmod ${path}

What it means

Vert.x wraps the java.nio.file.IOException thrown by Files.setPosixFilePermissions during FileSystem.chmod into a FileSystemException. It means the POSIX permission bits of the target path could not be changed. SecurityException yields a separate 'Accessed denied' variant; this one covers all other I/O failures such as a missing file or a filesystem that does not support POSIX permissions.

Source

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

              public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs) throws IOException {
                //The directory entries typically have different permissions to the files, e.g. execute permission
                //or can't cd into it
                Files.setPosixFilePermissions(dir, dirPermissions);
                return FileVisitResult.CONTINUE;
              }

              public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) throws IOException {
                Files.setPosixFilePermissions(file, permissions);
                return FileVisitResult.CONTINUE;
              }
            });
          } else {
            Files.setPosixFilePermissions(target, permissions);
          }
        } catch (SecurityException e) {
          throw new FileSystemException("Accessed denied for chmod on " + path);
        } catch (IOException e) {
          throw new FileSystemException(getFileAccessErrorMessage("chmod", path), e);
        }
        return null;
      }
    };
  }

  protected BlockingAction<Void> chownInternal(String path, String user, String group) {
    Objects.requireNonNull(path);
    return new BlockingAction<Void>() {
      public Void perform() {
        try {
          Path target = resolveFile(path).toPath();
          UserPrincipalLookupService service = target.getFileSystem().getUserPrincipalLookupService();
          UserPrincipal userPrincipal = user == null ? null : service.lookupPrincipalByName(user);
          GroupPrincipal groupPrincipal = group == null ? null : service.lookupPrincipalByGroupName(group);
          if (groupPrincipal != null) {
            PosixFileAttributeView view = Files.getFileAttributeView(target, PosixFileAttributeView.class, LinkOption.NOFOLLOW_LINKS);
            if (view == null) {

View on GitHub (pinned to fb308bd8c3)

Solutions

  1. Verify the path exists (vertx.fileSystem().existsBlocking(path)) before chmod.
  2. Confirm the filesystem supports POSIX permissions; skip chmod or use ACLs on non-POSIX volumes.
  3. Check the nested cause (FileSystemException.getCause()) for the exact IOException reason.
  4. Ensure the process user has ownership of the file; PermissionDenied surfaces as the separate SecurityException variant.

Example fix

// before
vertx.fileSystem().chmod("/app/conf", "rwxr-x---");
// after
vertx.fileSystem().exists("/app/conf").onSuccess(ok -> {
  if (ok) vertx.fileSystem().chmod("/app/conf", "rwxr-x---");
});
Defensive patterns

Strategy: try-catch

Validate before calling

if (!vertx.fileSystem().existsBlocking(path)) throw new IllegalStateException("cannot chmod missing path: " + path);

Try / catch

try { vertx.fileSystem().chmodBlocking(path, perms); } catch (FileSystemException e) { log.error("chmod failed for {}: {}", path, e.getCause(), e); }

Prevention

When it happens

Trigger: Calling vertx.fileSystem().chmod(path, perms) (or chmodBlocking) when the path does not exist, the path is on a non-POSIX filesystem (e.g. Windows FAT, some network mounts), or the underlying Files.setPosixFilePermissions call raises IOException.

Common situations: Typo in the path passed to chmod; running inside a container where the mounted volume does not support chmod; chmod on a Windows filesystem; race where the file is deleted between check and chmod.

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

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