apache/iceberg · error · AlreadyExistsException

Location already exists: %s

Error message

Location already exists: %s

What it means

ADLSOutputFile.create() refuses to overwrite an existing file: it checks existence first and throws AlreadyExistsException if the location already has content. Use createOrOverwrite() if overwriting is intended.

Source

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

      String location,
      DataLakeFileClient fileClient,
      AzureProperties azureProperties,
      MetricsContext metrics) {
    super(location, fileClient, azureProperties, metrics);
  }

  /**
   * Create an output stream for the specified location if the target object does not exist in Azure
   * 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

1. Delete the existing file or use a new unique file name/path.
2. Call createOrOverwrite() instead of create() if overwriting is acceptable.
3. Clean up stale output from previous failed runs before retrying the write.

Example fix

// before
PositionOutputStream out = outputFile.create();
// after
PositionOutputStream out = outputFile.createOrOverwrite(); // or ensure the file does not exist

if (outputFile.exists()) { // choose: delete, pick a new name, or use createOrOverwrite()
}

try { out = outputFile.create(); } catch (AlreadyExistsException e) { out = outputFile.createOrOverwrite(); // or generate a new unique path
}

When it happens

Trigger: Calling ADLSOutputFile.create() when a blob already exists at the target location.

Common situations: Retrying a failed write without cleaning up a partially created file; a leftover file from a previous job run; two writers targeting the same path.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

• Location does not exist: %s
• Failed to create output stream for location:
• Failed to close the VendedAdlsCredentialProvider
• Failed to delete path: {}
• Unable to load metrics class: '{}', falling back to null met

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