eclipse-vertx/vert.x · error · FileSystemException

Failed to create ${path}

Error message

Failed to create ${path}

What it means

Thrown when FileSystem.mkdir / mkdirs fails: Vert.x calls Files.createDirectory (with POSIX attrs when perms are given) and wraps any IOException into a FileSystemException via getFolderAccessErrorMessage("create", path) — 'Failed to create <path>'. Note mkdir (not mkdirs) fails if a parent directory is missing or the directory already exists.

Source

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

    return new BlockingAction<Void>() {
      public Void perform() {
        try {
          Path source = resolveFile(path).toPath();
          if (createParents) {
            if (attrs != null) {
              Files.createDirectories(source, attrs);
            } else {
              Files.createDirectories(source);
            }
          } else {
            if (attrs != null) {
              Files.createDirectory(source, attrs);
            } else {
              Files.createDirectory(source);
            }
          }
        } catch (IOException e) {
          throw new FileSystemException(getFolderAccessErrorMessage("create", path), e);
        }
        return null;
      }
    };
  }

  protected BlockingAction<String> createTempDirectoryInternal(String parentDir, String prefix, String perms) {
    FileAttribute<?> attrs = perms == null ? null : PosixFilePermissions.asFileAttribute(PosixFilePermissions.fromString(perms));
    return new BlockingAction<String>() {
      public String perform() {
        try {
          Path tmpDir;
          if (parentDir != null) {
            Path dir = resolveFile(parentDir).toPath();
            if (attrs != null) {
              tmpDir = Files.createTempDirectory(dir, prefix, attrs);
            } else {
              tmpDir = Files.createTempDirectory(dir, prefix);

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Use mkdirs/mkdirsBlocking to create all missing parent directories.
2. Check existsBlocking(path) first, or treat FileAlreadyExistsException in the cause as success.
3. Verify write permission on the parent directory.
4. Pass valid POSIX perms string if using the perms overload (e.g. "rwxr-x---").

Example fix

// before
vertx.fileSystem().mkdirBlocking("/app/data/cache/v2"); // parent missing
// after
vertx.fileSystem().mkdirsBlocking("/app/data/cache/v2");

FileSystem fs = vertx.fileSystem();
if (!fs.existsBlocking(path)) fs.mkdirsBlocking(path, perms); // idempotent create

try { vertx.fileSystem().mkdirBlocking(path, perms); } catch (FileSystemException e) { if (e.getCause() instanceof FileAlreadyExistsException) { /* ok */ } else throw e; }

When it happens

Trigger: vertx.fileSystem().mkdir(path) or mkdir(path, perms) when the parent directory does not exist, the directory already exists (FileAlreadyExistsException), or the parent is not writable.

Common situations: Creating a deeply nested path with mkdir instead of mkdirs; output directories that already exist from a previous run; read-only volume or missing write permission in containers.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

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