eclipse-vertx/vert.x · error · FileSystemException

Unable to create temporary file with prefix '${prefix}' and

Error message

Unable to create temporary file with prefix '${prefix}' and suffix '${suffix}' at ${parentDir}

What it means

Vert.x's FileSystemImpl throws this FileSystemException when it fails to create a temporary file via File.createTempFile (or equivalent) for operations like unzipping resources to a temp location. The wrapped IOException (cause) holds the underlying OS-level reason, such as a missing, read-only, or full temp directory.

Source

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

            Path dir = resolveFile(parentDir).toPath();
            if (attrs != null) {
              tmpFile = Files.createTempFile(dir, prefix, suffix, attrs);
            } else {
              tmpFile = Files.createTempFile(dir, prefix, suffix);
            }
          } else {
            if (attrs != null) {
              tmpFile = Files.createTempFile(prefix, suffix, attrs);
            } else {
              tmpFile = Files.createTempFile(prefix, suffix);
            }
          }
          return tmpFile.toFile().getAbsolutePath();
        } catch (IOException e) {
          final String message = "Unable to create temporary file with prefix '" + prefix
            + "' and suffix '" + suffix
            + "' at " + parentDir;
          throw new FileSystemException(message, e);
        }
      }
    };
  }

  private BlockingAction<List<String>> readDirInternal(String path) {
    return readDirInternal(path, null);
  }

  private BlockingAction<List<String>> readDirInternal(String p, String filter) {
    Objects.requireNonNull(p);
    return new BlockingAction<List<String>>() {
      public List<String> perform() {
        try {
          File file = resolveFile(p);
          if (!file.exists()) {
            throw new FileSystemException("Cannot read directory " + file + ". Does not exist");
          }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Check that the parent directory (usually java.io.tmpdir) exists and is writable by the process user
2. Free disk space or raise the quota on the temp filesystem
3. Set -Djava.io.tmpdir to a valid writable directory, or set the TMPDIR env var accordingly
4. Inspect the chained cause IOException for the precise OS error and fix that underlying issue

Example fix

// before (read-only /tmp in container)
java -jar app.jar
// after
java -Djava.io.tmpdir=/var/tmp -jar app.jar

java.io.File tmp = new File(System.getProperty("java.io.tmpdir"));
if (!tmp.isDirectory() || !tmp.canWrite() || tmp.getUsableSpace() < 1024*1024) {
  throw new IllegalStateException("Temp directory not usable: " + tmp);
}

try {
  fs.readFile(path);
} catch (FileSystemException e) {
  logger.error("temp file creation failed: " + e.getCause(), e);
  // redirect java.io.tmpdir or free disk space, then retry
}

When it happens

Trigger: Calling a Vert.x FileSystem/API operation that needs a scratch temp file (e.g. resolving a classpath resource by extracting it) when java.io.tmpdir is missing, not writable, or the disk is full.

Common situations: Containers running with a read-only root filesystem, TMPDIR pointing to a deleted directory, disk quota exceeded on /tmp, or security manager/file-permission restrictions blocking temp file creation.

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}
• 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/3370dbc8926445fe. Report an issue: GitHub.