apache/iceberg · error · UncheckedIOException

Failed to create output stream for location

Error message

Failed to create output stream for location: ${uri}

What it means

GCSOutputFile.createOrOverwrite() wraps IOException from constructing the GCSOutputStream into UncheckedIOException with the target URI. It means the output stream for the GCS blob could not be opened (write channel creation failed), not that the location already exists.

Solutions

1. Check GCS credentials and project/bucket configuration
2. Verify the bucket and path (blobId) actually exist and are writable
3. Retry on transient IOException (network flake)
4. Inspect the chained cause IOException for the root reason

Example fix

// before
throw new RuntimeException(e);
// after
try {
  PositionOutputStream os = file.createOrOverwrite();
} catch (UncheckedIOException e) {
  LOG.error("Failed writing to {}", file.location(), e.getCause());
  throw e;
}

// verify bucket exists via storage().get(bucket) and credentials via storage().list(bucket, Storage.BlobListOption.pageSize(1))

try { os = file.createOrOverwrite(); } catch (UncheckedIOException e) { /* inspect e.getCause(); retry transient failures */ }

When it happens

Trigger: Calling createOrOverwrite() (directly or via create() on a fresh path) when GCS storage() fails to open a write channel — e.g. invalid blob id, credentials or network failure while creating GCSOutputStream.

Common situations: Expired or missing GCP credentials; bucket removed or renamed; transient network/GCS outage; bad path escaping producing an invalid blobId.

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

• Failed to create shredded variant writer
• Failed to process task iterable:
• Failed to process tasks iterable
• Location already exists
• Location does not exist

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

Appendix: source

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

   * 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)