eclipse-vertx/vert.x · error · FileSystemException

Failed to create subfolder of ${parentDir}

Error message

Failed to create subfolder of ${parentDir}

What it means

Thrown when FileSystem.createTempDirectory fails: Vert.x calls Files.createTempDirectory (in parentDir when given, with POSIX attrs for perms) and wraps IOException into a FileSystemException via getFolderAccessErrorMessage("create subfolder of", parentDir) — 'Failed to create subfolder of <parentDir>'. The temporary directory could not be created at the requested location.

Source

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

        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);
            }
          } else {
            if (attrs != null) {
              tmpDir = Files.createTempDirectory(prefix, attrs);
            } else {
              tmpDir = Files.createTempDirectory(prefix);
            }
          }
          return tmpDir.toFile().getAbsolutePath();
        } catch (IOException e) {
          throw new FileSystemException(getFolderAccessErrorMessage("create subfolder of", parentDir), e);
        }
      }
    };
  }

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

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Ensure parentDir exists and is writable, or pass null to use the system temp dir.
2. Check disk space on the temp filesystem (df -h /tmp).
3. Set -Djava.io.tmpdir to a writable location if the default is not writable.
4. Inspect getCause() for AccessDeniedException vs FileSystemException (no space).

Example fix

// before
vertx.fileSystem().createTempDirectoryBlocking("/app/tmp", "work-", ".d", null); // /app/tmp missing
// after
vertx.fileSystem().mkdirsBlocking("/app/tmp");
vertx.fileSystem().createTempDirectoryBlocking("/app/tmp", "work-", ".d", null);

if (parentDir != null && (!vertx.fileSystem().existsBlocking(parentDir) || !vertx.fileSystem().propsBlocking(parentDir).isDirectory())) throw new IllegalArgumentException("bad temp parent: " + parentDir);

try { return vertx.fileSystem().createTempDirectoryBlocking(parentDir, prefix, suffix, perms); } catch (FileSystemException e) { log.error("temp dir creation failed in {}: {}", parentDir, e.getCause(), e); throw e; }

When it happens

Trigger: vertx.fileSystem().createTempDirectory(dir, prefix, suffix, perms) when parentDir does not exist, is not writable, or (with no dir) the java.io.tmpdir location is unavailable or full.

Common situations: Passing a non-existent parentDir instead of null; read-only /tmp in containers (or tmpfs full); java.io.tmpdir pointing to a directory the process user cannot write; SELinux/AppArmor blocking temp creation.

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 chmod ${path}
• Failed to crown ${path}
• Failed to analyse ${path}
• Unable to link existing file '${existing}' to '${link}'
• Failed to read ${link}

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