{"record":{"id":"850677db70f8fc2a","repo":"apache/beam","slug":"failed-to-create-directory","errorCode":null,"errorMessage":"Failed to create directory: ","messagePattern":"Failed to create directory: ","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/util/ZipFiles.java","lineNumber":131,"sourceCode":"   *     zipFile} was not readable, or contains an illegal entry (contains \"..\", pointing outside\n   *     the target directory)\n   * @throws IllegalArgumentException the target directory is not a valid directory (e.g. does not\n   *     exist, or is a file instead of a directory)\n   */\n  static void unzipFile(File zipFile, File targetDirectory) throws IOException {\n    checkNotNull(zipFile);\n    checkNotNull(targetDirectory);\n    checkArgument(\n        targetDirectory.isDirectory(),\n        \"%s is not a valid directory\",\n        targetDirectory.getAbsolutePath());\n    try (ZipFile zipFileObj = new ZipFile(zipFile)) {\n      for (ZipEntry entry : entries(zipFileObj)) {\n        checkName(entry.getName());\n        File targetFile = new File(targetDirectory, entry.getName());\n        if (entry.isDirectory()) {\n          if (!targetFile.isDirectory() && !targetFile.mkdirs()) {\n            throw new IOException(\"Failed to create directory: \" + targetFile.getAbsolutePath());\n          }\n        } else {\n          File parentFile = targetFile.getParentFile();\n          if (!parentFile.isDirectory() && !parentFile.mkdirs()) {\n            throw new IOException(\"Failed to create directory: \" + parentFile.getAbsolutePath());\n          }\n          // Write the file to the destination.\n          asByteSource(zipFileObj, entry).copyTo(Files.asByteSink(targetFile));\n        }\n      }\n    }\n  }\n\n  /**\n   * Checks that the given entry name is legal for unzipping: if it contains \"..\" as a name element,\n   * it could cause the entry to be unzipped outside the directory we're unzipping to.\n   *\n   * @throws IOException if the name is illegal","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/util/ZipFiles.java#L113-L149","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Check filesystem permissions on targetDirectory and ensure the process can write there","Remove or rename any existing file that conflicts with a directory entry name in the zip","Inspect the zip for entries with illegal characters for the target OS filesystem","Use a fresh, empty target directory"],"exampleFix":"// before\nZipFiles.unzipFile(zipPath, Paths.get(\"/ro/mount/out\"));\n// after\nFile out = Paths.get(\"/tmp/out\").toFile();\nif (!out.canWrite()) { throw new IllegalStateException(\"target not writable\"); }\nZipFiles.unzipFile(zipPath, out.toPath());","handlingStrategy":"validation","validationCode":"File target = targetDirectory.toFile();\nif (!target.exists() && !target.mkdirs()) throw new IOException(\"cannot create \" + target);\nif (!target.canWrite()) throw new IOException(\"not writable: \" + target);","typeGuard":null,"tryCatchPattern":"try {\n  ZipFiles.unzipFile(zip, targetDir);\n} catch (IOException e) {\n  if (e.getMessage().startsWith(\"Failed to create directory\")) {\n    throw new IOException(\"extraction blocked at: \" + e.getMessage(), e);\n  }\n  throw e;\n}","preventionTips":["Unzip into a fresh empty directory","Check write permissions before extraction","Validate entry names against OS filesystem constraints"],"tags":["java","io","zip","filesystem"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}