{"record":{"id":"1bd83e5449a06830","repo":"apache/iceberg","slug":"failed-to-create-the-file-s-directory-at-s","errorCode":null,"errorMessage":"Failed to create the file's directory at %s.","messagePattern":"Failed to create the file's directory at (.+?)\\.","errorType":"exception","errorClass":"RuntimeIOException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/org/apache/iceberg/Files.java","lineNumber":63,"sourceCode":"    }\n    return localOutput(Paths.get(file).toAbsolutePath().toFile());\n  }\n\n  private static class LocalOutputFile implements OutputFile {\n    private final File file;\n\n    private LocalOutputFile(File file) {\n      this.file = file;\n    }\n\n    @Override\n    public PositionOutputStream create() {\n      if (file.exists()) {\n        throw new AlreadyExistsException(\"File already exists: %s\", file);\n      }\n\n      if (!file.getParentFile().isDirectory() && !file.getParentFile().mkdirs()) {\n        throw new RuntimeIOException(\n            \"Failed to create the file's directory at %s.\", file.getParentFile().getAbsolutePath());\n      }\n\n      try {\n        return new PositionFileOutputStream(file, new RandomAccessFile(file, \"rw\"));\n      } catch (FileNotFoundException e) {\n        throw new NotFoundException(e, \"Failed to create file: %s\", file);\n      }\n    }\n\n    @Override\n    public PositionOutputStream createOrOverwrite() {\n      if (file.exists() && !file.delete()) {\n        throw new RuntimeIOException(\"Failed to delete: %s\", file);\n      }\n      return create();\n    }\n","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/api/src/main/java/org/apache/iceberg/Files.java#L45-L81","documentation":"Before creating the file, create() ensures the parent directory exists via mkdirs(). If the parent is not a directory and cannot be created, it throws RuntimeIOException reporting the parent path, typically due to filesystem permissions, an existing non-directory file at that path, or an invalid/illegal path.","triggerScenarios":"Writing through local FileIO when the parent path segment exists as a regular file, the process lacks write permission on the parent, or the location string maps to an invalid path (e.g. path exists as a file where a directory is expected).","commonSituations":"Misconfigured warehouse root where a file occupies the directory path; read-only mount or container filesystem; running as a user without permission to create the table's data/metadata directories.","solutions":["Check the parent path: if a regular file exists at it, remove/rename it or choose a different location","Verify write permissions on the parent directory for the process user (ls -ld, chown/chmod)","Validate the warehouse/table location configuration points at a valid directory path"],"exampleFix":"// before\nFile parent = new File(path).getParentFile();\nOutputFile out = fileIO.newOutputFile(path);\nPositionOutputStream s = out.create();\n// after\nFile parent = new File(path).getParentFile();\nif (!parent.isDirectory() && !parent.mkdirs()) {\n  throw new IllegalStateException(\"Cannot create directory: \" + parent);\n}\nPositionOutputStream s = fileIO.newOutputFile(path).create();","handlingStrategy":"validation","validationCode":"File parent = new File(URI.create(location).getPath()).getParentFile();\nPreconditions.checkState(parent != null && (parent.isDirectory() || parent.mkdirs()),\n    \"Cannot create parent dir: %s\", parent);","typeGuard":null,"tryCatchPattern":"try {\n  stream = outputFile.create();\n} catch (RuntimeIOException e) {\n  throw new IllegalStateException(\"Check parent dir permissions/path: \" + e.getMessage(), e);\n}","preventionTips":["Verify warehouse location is a writable directory before jobs run","Ensure no regular file occupies a parent path segment","Run processes with a user that owns or can write the warehouse tree"],"tags":["java","fileio","mkdir","permissions"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}