apache/iceberg · error · RuntimeIOException

Failed to create the file's directory at %s.

Error message

Failed to create the file's directory at %s.

What it means

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.

Source

Thrown at api/src/main/java/org/apache/iceberg/Files.java:63

    }
    return localOutput(Paths.get(file).toAbsolutePath().toFile());
  }

  private static class LocalOutputFile implements OutputFile {
    private final File file;

    private LocalOutputFile(File file) {
      this.file = file;
    }

    @Override
    public PositionOutputStream create() {
      if (file.exists()) {
        throw new AlreadyExistsException("File already exists: %s", file);
      }

      if (!file.getParentFile().isDirectory() && !file.getParentFile().mkdirs()) {
        throw new RuntimeIOException(
            "Failed to create the file's directory at %s.", file.getParentFile().getAbsolutePath());
      }

      try {
        return new PositionFileOutputStream(file, new RandomAccessFile(file, "rw"));
      } catch (FileNotFoundException e) {
        throw new NotFoundException(e, "Failed to create file: %s", file);
      }
    }

    @Override
    public PositionOutputStream createOrOverwrite() {
      if (file.exists() && !file.delete()) {
        throw new RuntimeIOException("Failed to delete: %s", file);
      }
      return create();
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Check the parent path: if a regular file exists at it, remove/rename it or choose a different location
  2. Verify write permissions on the parent directory for the process user (ls -ld, chown/chmod)
  3. Validate the warehouse/table location configuration points at a valid directory path

Example fix

// before
File parent = new File(path).getParentFile();
OutputFile out = fileIO.newOutputFile(path);
PositionOutputStream s = out.create();
// after
File parent = new File(path).getParentFile();
if (!parent.isDirectory() && !parent.mkdirs()) {
  throw new IllegalStateException("Cannot create directory: " + parent);
}
PositionOutputStream s = fileIO.newOutputFile(path).create();
Defensive patterns

Strategy: validation

Validate before calling

File parent = new File(URI.create(location).getPath()).getParentFile();
Preconditions.checkState(parent != null && (parent.isDirectory() || parent.mkdirs()),
    "Cannot create parent dir: %s", parent);

Try / catch

try {
  stream = outputFile.create();
} catch (RuntimeIOException e) {
  throw new IllegalStateException("Check parent dir permissions/path: " + e.getMessage(), e);
}

Prevention

When it happens

Trigger: 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).

Common situations: 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.

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/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/1bd83e5449a06830. Report an issue: GitHub.