{"record":{"id":"540a14bfef476800","repo":"apache/iceberg","slug":"failed-to-create-file-s-540a14","errorCode":null,"errorMessage":"Failed to create file: %s","messagePattern":"Failed to create file: (.+?)","errorType":"exception","errorClass":"NotFoundException","httpStatus":404,"severity":"error","filePath":"api/src/main/java/org/apache/iceberg/Files.java","lineNumber":70,"sourceCode":"    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\n    @Override\n    public String location() {\n      return file.toString();\n    }\n\n    @Override\n    public InputFile toInputFile() {","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/api/src/main/java/org/apache/iceberg/Files.java#L52-L88","documentation":"After validating existence and parent directory, create() opens the file with new RandomAccessFile(file, \"rw\"). A FileNotFoundException here means the file could not be opened (e.g. permission denied, path is a directory, or too many open files), wrapped as NotFoundException with the target file in the message.","triggerScenarios":"Parent directory exists and file doesn't, but opening \"rw\" fails: process lacks permission to create files in the directory, a directory exists at the target path, the filesystem is full/read-only, or the file was deleted between the exists() check and open.","commonSituations":"Read-only volumes or sandboxed processes writing outside allowed dirs; SELinux/AppArmor denials; ulimit -n exhaustion in long-running jobs; racing writers deleting the same path.","solutions":["Verify the process can create files in the parent directory (touch a test file as the same user)","Ensure the target path is not an existing directory and the filesystem is writable and not full","Check open-file limits (ulimit -n) if this occurs under heavy concurrency; close leaked streams"],"exampleFix":"// before\nPositionOutputStream s = fileIO.newOutputFile(dir + \"/data\").create();\n// after\nFile target = new File(dir + \"/data\");\nPreconditions.checkArgument(!target.isDirectory(), \"Path is a directory: %s\", target);\nPositionOutputStream s = fileIO.newOutputFile(target.getPath()).create();","handlingStrategy":"validation","validationCode":"File f = new File(URI.create(location).getPath());\nPreconditions.checkState(!f.isDirectory(), \"Target is a directory: %s\", f);\nPreconditions.checkState(f.getParentFile().canWrite(), \"Parent not writable: %s\", f.getParentFile());","typeGuard":null,"tryCatchPattern":"try {\n  stream = outputFile.create();\n} catch (NotFoundException e) {\n  throw new IllegalStateException(\"File open failed: \" + e.getMessage(), e);\n}","preventionTips":["Check filesystem writability and free space before bulk writes","Raise ulimit -n for jobs opening many files","Never delete target files from concurrent writers"],"tags":["java","fileio","io","permissions"],"backgroundTag":"file-open-failed","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"}