apache/iceberg · error · UncheckedIOException

Failed to create output stream for location:

Error message

Failed to create output stream for location: 

What it means

S3OutputFile.createOrOverwrite() wraps any IOException from constructing the S3OutputStream (e.g. failing to create the local staging file/directory) in an UncheckedIOException with this message. The S3 object upload stream could not even be set up.

Solutions

1. Check that s3.staging-directory (or the default tmp dir) exists and is writable by the process user.
2. Fix disk space/permissions on the staging volume.
3. Inspect the wrapped IOException cause for the root failure.
4. Point staging to a local ephemeral volume with sufficient capacity.

Example fix

// before
properties.put("s3.staging-directory", "/mnt/nonexistent/staging");
// after
Files.createDirectories(Paths.get("/mnt/staging"));
properties.put("s3.staging-directory", "/mnt/staging");

// Java
File staging = new File(props.stagingDirectory());
if (!(staging.exists() || staging.mkdirs()) || !staging.canWrite()) {
  throw new IllegalStateException("Staging dir unusable: " + staging);
}

// Java
try {
  os = outFile.createOrOverwrite();
} catch (UncheckedIOException e) {
  LOG.error("Staging setup failed: {}", e.getCause());
  throw e; // fix staging config; retrying alone won't help
}

When it happens

Trigger: Creating the output stream when the configured staging directory is unwritable, missing, or full; File.createTempFile fails due to permissions or disk space.

Common situations: s3.staging-dir points to a nonexistent or non-writable path in containers/EMR nodes; /tmp is read-only or full; running with a restricted filesystem in Kubernetes.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• An error occurred while aborting the stream
• An error occurred while closing the stream
• Failed to create S3 analytics accelerator input stream for
• Failed to create staging directory due to some unknown…
• Location already exists

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

Appendix: source

Thrown at aws/src/main/java/org/apache/iceberg/aws/s3/S3OutputFile.java:75

   * the time of invocation.
   *
   * @return output stream
   */
  @Override
  public PositionOutputStream create() {
    if (!exists()) {
      return createOrOverwrite();
    } else {
      throw new AlreadyExistsException("Location already exists: %s", uri());
    }
  }

  @Override
  public PositionOutputStream createOrOverwrite() {
    try {
      return new S3OutputStream(client(), uri(), s3FileIOProperties(), metrics());
    } catch (IOException e) {
      throw new UncheckedIOException("Failed to create output stream for location: " + uri(), e);
    }
  }

  @Override
  public InputFile toInputFile() {
    return new S3InputFile(client(), asyncClient(), uri(), null, s3FileIOProperties(), metrics());
  }

  @Override
  public NativeFileCryptoParameters nativeCryptoParameters() {
    return nativeEncryptionParameters;
  }

  @Override
  public void setNativeCryptoParameters(NativeFileCryptoParameters nativeCryptoParameters) {
    this.nativeEncryptionParameters = nativeCryptoParameters;
  }
}

View on GitHub (pinned to 86d9c8fc54)