apache/iceberg · error · AlreadyExistsException

Location already exists

Error message

Location already exists: %s

What it means

GCSOutputFile.create() throws AlreadyExistsException when the target GCS blob already exists. The library treats create() as strictly create-new: it checks blob existence first and refuses to overwrite, forcing callers to choose between create() and createOrOverwrite() explicitly. This prevents silent data loss from accidental overwrites.

Solutions

1. Delete the existing blob or use a unique/new output location before calling create()
2. Call createOrOverwrite() instead of create() if overwriting is intended
3. Enable unique/metadata-location output naming (e.g. include attempt ID or UUID in the path)
4. Handle AlreadyExistsException and pick an alternative location

Example fix

// before
OutputFile out = table.io().newOutputFile(location);
PositionOutputStream os = out.create();
// after
PositionOutputStream os = out.createOrOverwrite(); // or ensure location is fresh/delete blob first

if (((GCSOutputFile) out).exists()) { /* delete or pick new location */ }

try { os = out.create(); } catch (AlreadyExistsException e) { os = out.createOrOverwrite(); /* or relocate */ }

When it happens

Trigger: Calling GCSOutputFile.create() when a blob already exists at the file's URI; e.g. writing an output file to a path that a previous job already wrote.

Common situations: Re-running a batch/Spark job that writes to the same output path; concurrent writers racing to the same location; misconfigured output path pointing at an existing file.

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

• Failed to create output stream for location
• Location does not exist
• Reached the end of stream with X bytes left to read
• An error occurred while aborting the stream
• An error occurred while closing the stream

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

Appendix: source

Thrown at gcp/src/main/java/org/apache/iceberg/gcp/gcs/GCSOutputFile.java:66

      AutoCloseable gcsFileSystem,
      BlobId blobId,
      GCPProperties gcpProperties,
      MetricsContext metrics) {
    super(storage, gcsFileSystem, blobId, gcpProperties, metrics);
  }

  /**
   * Create an output stream for the specified location if the target object does not exist in GCS
   * at 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 GCSOutputStream(storage(), blobId(), gcpProperties(), metrics());
    } catch (IOException e) {
      throw new UncheckedIOException("Failed to create output stream for location: " + uri(), e);
    }
  }

  @Override
  public InputFile toInputFile() {
    return new GCSInputFile(storage(), gcsFileSystem(), blobId(), null, gcpProperties(), metrics());
  }
}

View on GitHub (pinned to 86d9c8fc54)