What causes "Failed to create file: %s" in apache/iceberg?

Ensure the local staging/tmp directory exists and is writable by the process user.

apache/iceberg · error · NotFoundException

Failed to create file: %s

Error message

Failed to create file: %s

What it means

OSSOutputStream stages written data in a local temporary file before uploading to OSS. newStream opens a FileOutputStream on that staging file; if the file cannot be created/opened (FileNotFoundException), it throws NotFoundException("Failed to create file: <path>"). This is a local-disk problem, not an OSS problem.

Source

Thrown at aliyun/src/main/java/org/apache/iceberg/aliyun/oss/OSSOutputStream.java:86

    this.stream = newStream(currentStagingFile);
    this.writeBytes = metrics.counter(FileIOMetricsContext.WRITE_BYTES, Unit.BYTES);
    this.writeOperations = metrics.counter(FileIOMetricsContext.WRITE_OPERATIONS);
  }

  private static File newStagingFile(String ossStagingDirectory) {
    try {
      File stagingFile = File.createTempFile("oss-file-io-", ".tmp", new File(ossStagingDirectory));
      return stagingFile;
    } catch (IOException e) {
      throw new UncheckedIOException(e);
    }
  }

  private static OutputStream newStream(File currentStagingFile) {
    try {
      return new BufferedOutputStream(new FileOutputStream(currentStagingFile));
    } catch (FileNotFoundException e) {
      throw new NotFoundException(e, "Failed to create file: %s", currentStagingFile);
    }
  }

  private static InputStream uncheckedInputStream(File file) {
    try {
      return new FileInputStream(file);
    } catch (IOException e) {
      throw new UncheckedIOException(e);
    }
  }

  @Override
  public long getPos() {
    return pos;
  }

  @Override
  public void flush() throws IOException {

View on GitHub (pinned to 86d9c8fc54)

Solutions

Ensure the local staging/tmp directory exists and is writable by the process user.
Set a valid java.io.tmpdir / staging location with free disk space.
Check disk usage and quotas on the node (df -h) and clean space if full.
Fix filesystem permissions (chmod/chown) on the staging directory.

Example fix

// before
spark-submit ... # tmpdir default may be unwritable

// after
spark-submit --conf spark.local.dir=/mnt/writable/spark-tmp \
  -Djava.io.tmpdir=/mnt/writable/tmp ...

Defensive patterns

Strategy: validation

Validate before calling

Path tmp = Path.of(System.getProperty("java.io.tmpdir"));
if (!Files.isDirectory(tmp) || !Files.isWritable(tmp)) {
  throw new IllegalStateException("Local staging dir not writable: " + tmp);
}

Prevention

Provision executors with adequate free disk and writable java.io.tmpdir.
Monitor disk usage (df) on nodes running OSS writes.
Run processes as users with write access to the staging directory.
Prefer local SSD scratch space for staging large files.

When it happens

Trigger: Constructing OSSOutputStream when the staging directory does not exist, is not writable, disk is full, or the temp path is invalid (permissions, read-only FS, missing parent dir).

Common situations: Containers with small/empty /tmp; java.io.tmpdir pointing to a read-only or removed directory; disk quota exceeded on executor nodes; running as a user without write permission to the staging dir.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/4325a4bbcf25d103. Report an issue: GitHub.