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

Check for existing files first or handle FileAlreadyExistsException from the cause

eclipse-vertx/vert.x · error · FileSystemException

Failed to create ${p}

Error message

Failed to create ${p}

What it means

Wrapped error in createFileInternal: Files.createFile (with or without POSIX attributes) threw an IOException, typically because the file already exists or the parent directory is missing. The raw path is reported and the concrete cause is attached.

Source

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

  private BlockingAction<Void> createFileInternal(String path) {
    return createFileInternal(path, null);
  }

  protected BlockingAction<Void> createFileInternal(String p, String perms) {
    Objects.requireNonNull(p);
    FileAttribute<?> attrs = perms == null ? null : PosixFilePermissions.asFileAttribute(PosixFilePermissions.fromString(perms));
    return new BlockingAction<Void>() {
      public Void perform() {
        try {
          Path target = resolveFile(p).toPath();
          if (attrs != null) {
            Files.createFile(target, attrs);
          } else {
            Files.createFile(target);
          }
        } catch (IOException e) {
          throw new FileSystemException(getFileAccessErrorMessage("create", p), e);
        }
        return null;
      }
    };
  }

  private BlockingAction<Boolean> existsInternal(String path) {
    Objects.requireNonNull(path);
    return new BlockingAction<Boolean>() {
      public Boolean perform() {
        File file = resolveFile(path);
        return file.exists();
      }
    };
  }

  private BlockingAction<FileSystemProps> fsPropsInternal(String path) {
    Objects.requireNonNull(path);

View on GitHub (pinned to fb308bd8c3)

Solutions

Check for existing files first or handle FileAlreadyExistsException from the cause
Create parent directories before creating the file
Verify write permissions

Example fix

// before
vertx.fileSystem().createFile("locks/job.lock");
// after
vertx.fileSystem().mkdirs("locks")
  .compose(v -> vertx.fileSystem().createFile("locks/job.lock"));

Defensive patterns

Strategy: try-catch

Validate before calling

Path target = Path.of(path);
if (Files.exists(target)) {
  // decide: skip or delete first
} else if (!Files.isDirectory(target.getParent())) {
  Files.createDirectories(target.getParent());
}

Try / catch

try {
  fs.createFile(path);
} catch (FileSystemException e) {
  if (e.getCause() instanceof java.nio.file.FileAlreadyExistsException) {
    // treat as success or delete-and-recreate
  } else {
    logger.error("createFile failed: {}", e.getCause());
  }
}

Prevention

Check existence first for idempotent creation
Create parent directories beforehand
Run as a user with write access to the target directory

When it happens

Trigger: Calling FileSystem.createFile(path) or createFile(path, attrs) when the parent directory does not exist, permission is denied, or the file already exists (NoSuchFileException/FileAlreadyExistsException are IOExceptions too).

Common situations: Creating marker/lock files in directories that were never created, race conditions where the file already exists, or writing into read-only locations.

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/0c9f49b6b8991813. Report an issue: GitHub.