apache/iceberg · error · AlreadyExistsException

ECS object already exists

Error message

ECS object already exists: %s

What it means

AlreadyExistsException from EcsOutputFile.create: this create() must not clobber, and an object already exists at the target ECS URI (the exists() check passed into this branch). The %s is the EcsURI; callers wanting to overwrite should call createOrOverwrite() instead.

Solutions

1. Use createOrOverwrite() when overwriting is intended
2. Generate unique file names (UUID) per write
3. Check existence with exists() first or catch AlreadyExistsException

Example fix

// before
outputFile.create();
// after
outputFile.createOrOverwrite(); // or catch AlreadyExistsException

if (!outputFile.exists()) { stream = outputFile.create(); } else { stream = outputFile.createOrOverwrite(); }

try { stream = outputFile.create(); } catch (AlreadyExistsException e) { stream = outputFile.createOrOverwrite(); }

When it happens

Trigger: Calling outputFile.create() when an object at the URI already exists, e.g. writing to the same data/metadata path twice.

Common situations: Job retry writing the same file path, non-unique filename generation (e.g. using timestamps with low resolution), intentional overwrite attempted via create() instead of createOrOverwrite().

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

• Already exists
• Can't create file
• Cannot create namespace
• Cannot create namespace
• Cannot create namespace

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

Appendix: source

Thrown at dell/src/main/java/org/apache/iceberg/dell/ecs/EcsOutputFile.java:63

  }

  EcsOutputFile(
      S3Client client, EcsURI uri, DellProperties dellProperties, MetricsContext metrics) {
    super(client, uri, dellProperties, metrics);
  }

  /**
   * Create an output stream for the specified location if the target object does not exist in ECS
   * at the time of invocation.
   *
   * @return output stream
   */
  @Override
  public PositionOutputStream create() {
    if (!exists()) {
      return createOrOverwrite();
    } else {
      throw new AlreadyExistsException("ECS object already exists: %s", uri());
    }
  }

  @Override
  public PositionOutputStream createOrOverwrite() {
    return EcsAppendOutputStream.create(client(), uri(), metrics());
  }

  @Override
  public InputFile toInputFile() {
    return new EcsInputFile(client(), uri(), dellProperties(), metrics());
  }
}

View on GitHub (pinned to 86d9c8fc54)