What causes "Failed to create output stream for location: " in apache/iceberg?

Inspect the wrapped IOException cause for the underlying Azure error and fix it.

apache/iceberg · error · UncheckedIOException

Failed to create output stream for location:

Error message

Failed to create output stream for location:

What it means

createOrOverwrite() wraps any IOException raised while constructing ADLSOutputStream (which opens the blob for writing) into an UncheckedIOException naming the location. This indicates the output stream could not be opened for the ADLS path.

Source

Thrown at azure/src/main/java/org/apache/iceberg/azure/adlsv2/ADLSOutputFile.java:61

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

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

  @Override
  public InputFile toInputFile() {
    return new ADLSInputFile(location(), fileClient(), azureProperties(), metrics());
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

Inspect the wrapped IOException cause for the underlying Azure error and fix it.
Verify the storage account name, container (filesystem), and path in the location are valid.
Check network access to the ADLS endpoint (VNet/firewall rules, private endpoints, DNS).
Verify the container exists and credentials can write to it.

Defensive patterns

Strategy: try-catch

Try / catch

try { out = outputFile.createOrOverwrite(); } catch (UncheckedIOException e) { log.error("Could not open output stream for {}: {}", location, e.getCause()); throw e; }

Prevention

Verify storage account, container, and path configuration before writes.
Ensure network/VNet/firewall rules allow egress to the ADLS endpoint.
Confirm write permissions on the container with a startup connectivity check.

When it happens

Trigger: new ADLSOutputStream(fileClient(), ...) throws IOException during blob open — storage account/container unreachable, invalid path, or Azure SDK open failure.

Common situations: Wrong storage account or container name in table location; network/ DNS problems reaching the ADLS endpoint; nonexistent filesystem/container; storage account misconfigured (e.g. firewall blocking access).

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

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