What causes "Failed to write ${path}" in eclipse-vertx/vert.x?

Create parent directories before writing (fs.mkdirs)

eclipse-vertx/vert.x · error · FileSystemException

Failed to write ${path}

Error message

Failed to write ${path}

What it means

Wrapped error in writeFileInternal: Files.write to the resolved target path threw an IOException. The message names the write operation and the raw path; the underlying cause (no such parent directory, permission denied, disk full) is attached.

Source

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

          }
        } catch (IOException e) {
          throw new FileSystemException(getFileAccessErrorMessage("read", path), e);
        }
      }
    };
  }

  private BlockingAction<Void> writeFileInternal(String path, Buffer data) {
    Objects.requireNonNull(path);
    Objects.requireNonNull(data);
    return new BlockingAction<Void>() {
      public Void perform() {
        try {
          Path target = resolveFile(path).toPath();
          Files.write(target, data.getBytes());
          return null;
        } catch (IOException e) {
          throw new FileSystemException(getFileAccessErrorMessage("write", path), e);
        }
      }
    };
  }

  private BlockingAction<AsyncFile> openInternal(String p, OpenOptions options) {
    Objects.requireNonNull(p);
    Objects.requireNonNull(options);
    return new BlockingAction<AsyncFile>() {
      public AsyncFile perform() {
        String path = resolveFile(p).getAbsolutePath();
        return doOpen(path, options, context);
      }
    };
  }

  protected AsyncFile doOpen(String path, OpenOptions options, ContextInternal context) {
    return new AsyncFileImpl(vertx, path, options, context);

View on GitHub (pinned to fb308bd8c3)

Solutions

Create parent directories before writing (fs.mkdirs)
Inspect the cause for permission or space issues
Verify the target path is writable

Example fix

// before
vertx.fileSystem().writeFile("out/result.json", buffer);
// after
vertx.fileSystem().mkdirs("out")
  .compose(v -> vertx.fileSystem().writeFile("out/result.json", buffer));

Defensive patterns

Strategy: try-catch

Validate before calling

Path target = Path.of(path);
if (!Files.isDirectory(target.getParent()) || !Files.isWritable(target.getParent())) {
  throw new IllegalStateException("Cannot write to: " + path);
}

Try / catch

try {
  fs.writeFile(path, data);
} catch (FileSystemException e) {
  logger.error("Write failed for {}: {}", path, e.getCause());
  // create dirs / fix permissions / free disk, then retry
}

Prevention

Create parent directories with mkdirs before writing
Verify write permission for the service user
Check free disk space and that the filesystem is not read-only

When it happens

Trigger: Calling FileSystem.writeFile(path, buffer) when the parent directory does not exist, the process lacks write permission, the target is a directory, or the disk is full.

Common situations: Writing to /etc or other root-owned paths from a non-root service, forgetting to create the output directory first, or read-only container filesystems.

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

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