apache/beam · error · IOException

Failed to create directory:

Error message

Failed to create directory:

What it means

ZipFiles.unzipFile throws this IOException when it cannot create a directory entry from the zip archive on disk via File.mkdirs(). This happens when the target path exists as a non-directory or the OS refuses creation (permissions, path length, invalid name). The message includes the absolute path that failed.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/ZipFiles.java:131

   *     zipFile} was not readable, or contains an illegal entry (contains "..", pointing outside
   *     the target directory)
   * @throws IllegalArgumentException the target directory is not a valid directory (e.g. does not
   *     exist, or is a file instead of a directory)
   */
  static void unzipFile(File zipFile, File targetDirectory) throws IOException {
    checkNotNull(zipFile);
    checkNotNull(targetDirectory);
    checkArgument(
        targetDirectory.isDirectory(),
        "%s is not a valid directory",
        targetDirectory.getAbsolutePath());
    try (ZipFile zipFileObj = new ZipFile(zipFile)) {
      for (ZipEntry entry : entries(zipFileObj)) {
        checkName(entry.getName());
        File targetFile = new File(targetDirectory, entry.getName());
        if (entry.isDirectory()) {
          if (!targetFile.isDirectory() && !targetFile.mkdirs()) {
            throw new IOException("Failed to create directory: " + targetFile.getAbsolutePath());
          }
        } else {
          File parentFile = targetFile.getParentFile();
          if (!parentFile.isDirectory() && !parentFile.mkdirs()) {
            throw new IOException("Failed to create directory: " + parentFile.getAbsolutePath());
          }
          // Write the file to the destination.
          asByteSource(zipFileObj, entry).copyTo(Files.asByteSink(targetFile));
        }
      }
    }
  }

  /**
   * Checks that the given entry name is legal for unzipping: if it contains ".." as a name element,
   * it could cause the entry to be unzipped outside the directory we're unzipping to.
   *
   * @throws IOException if the name is illegal

View on GitHub (pinned to 12126d8942)

Solutions

  1. Check filesystem permissions on targetDirectory and ensure the process can write there
  2. Remove or rename any existing file that conflicts with a directory entry name in the zip
  3. Inspect the zip for entries with illegal characters for the target OS filesystem
  4. Use a fresh, empty target directory

Example fix

// before
ZipFiles.unzipFile(zipPath, Paths.get("/ro/mount/out"));
// after
File out = Paths.get("/tmp/out").toFile();
if (!out.canWrite()) { throw new IllegalStateException("target not writable"); }
ZipFiles.unzipFile(zipPath, out.toPath());
Defensive patterns

Strategy: validation

Validate before calling

File target = targetDirectory.toFile();
if (!target.exists() && !target.mkdirs()) throw new IOException("cannot create " + target);
if (!target.canWrite()) throw new IOException("not writable: " + target);

Try / catch

try {
  ZipFiles.unzipFile(zip, targetDir);
} catch (IOException e) {
  if (e.getMessage().startsWith("Failed to create directory")) {
    throw new IOException("extraction blocked at: " + e.getMessage(), e);
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling ZipFiles.unzipFile(zipFile, targetDirectory) where a zip entry is marked isDirectory() but a file with that name already exists in targetDirectory, or mkdirs() fails due to permissions/read-only filesystem/invalid path characters.

Common situations: Extracting into a directory with pre-existing conflicting files; extracting a zip built on another OS with path-hostile names; running with restricted filesystem permissions (e.g. container read-only mounts).

Understand the failure class

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

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/850677db70f8fc2a. Report an issue: GitHub.