eclipse-vertx/vert.x · error · FileSystemException

Failed to crown ${path}

Error message

Failed to crown ${path}

What it means

Vert.x wraps the IOException thrown by Files.setOwner or principal lookup during FileSystem.chown into this FileSystemException (note the 'crown' wording comes from the internal getFileAccessErrorMessage("crown", path) call — a typo for 'chown'). It means the owner could not be changed for an I/O reason, not a security refusal.

Source

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

          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) {
              throw new FileSystemException("Change group of file not supported");
            }
            view.setGroup(groupPrincipal);

          }
          if (userPrincipal != null) {
            Files.setOwner(target, userPrincipal);
          }
        } catch (SecurityException e) {
          throw new FileSystemException("Accessed denied for chown on " + path);
        } catch (IOException e) {
          throw new FileSystemException(getFileAccessErrorMessage("crown", path), e);
        }
        return null;
      }
    };
  }

  private BlockingAction<FileProps> propsInternal(String path) {
    return props(path, true);
  }

  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() {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Check the cause: UserPrincipalNotFoundException means the user/group name is wrong — fix the name.
2. Verify the path exists before chown (existsBlocking).
3. On non-POSIX filesystems, skip chown and rely on volume-level ACL configuration.
4. Inspect the nested IOException via getCause() for the precise failure.

Example fix

// before
vertx.fileSystem().chown("/app/data", "apuser", null); // typo -> UserPrincipalNotFoundException
// after
vertx.fileSystem().chown("/app/data", "appuser", null);

if (!vertx.fileSystem().existsBlocking(path)) throw new IllegalStateException("missing path: " + path);
// also validate user/group names are resolvable on the host

try { vertx.fileSystem().chownBlocking(path, user, group); } catch (FileSystemException e) { Throwable c = e.getCause(); if (c instanceof UserPrincipalNotFoundException) { throw new IllegalArgumentException("unknown user/group: " + user + "/" + group); } throw e; }

When it happens

Trigger: Calling vertx.fileSystem().chown(path, user, group) when the path does not exist, the user/group principal name cannot be resolved by UserPrincipalLookupService (UserPrincipalNotFoundException extends IOException), or the filesystem does not support ownership.

Common situations: Misspelled username passed to chown; chown on a Windows or network filesystem that has no owner attribute; path deleted before the blocking action runs.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Failed to chmod ${path}
• Change group of file not supported
• Accessed denied for chown on ${path}
• Failed to analyse ${path}
• Unable to link existing file '${existing}' to '${link}'

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