{"record":{"id":"a443f41715390209","repo":"apache/iceberg","slug":"failed-to-create-output-stream-for-location-uri","errorCode":null,"errorMessage":"Failed to create output stream for location: ${uri}","messagePattern":"Failed to create output stream for location: (.+?)","errorType":"exception","errorClass":"UncheckedIOException","httpStatus":null,"severity":"error","filePath":"gcp/src/main/java/org/apache/iceberg/gcp/gcs/GCSOutputFile.java","lineNumber":75,"sourceCode":"   * at the time of invocation.\n   *\n   * @return output stream\n   */\n  @Override\n  public PositionOutputStream create() {\n    if (!exists()) {\n      return createOrOverwrite();\n    } else {\n      throw new AlreadyExistsException(\"Location already exists: %s\", uri());\n    }\n  }\n\n  @Override\n  public PositionOutputStream createOrOverwrite() {\n    try {\n      return new GCSOutputStream(storage(), blobId(), gcpProperties(), metrics());\n    } catch (IOException e) {\n      throw new UncheckedIOException(\"Failed to create output stream for location: \" + uri(), e);\n    }\n  }\n\n  @Override\n  public InputFile toInputFile() {\n    return new GCSInputFile(storage(), gcsFileSystem(), blobId(), null, gcpProperties(), metrics());\n  }\n}\n","sourceCodeStart":57,"sourceCodeEnd":84,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/gcp/src/main/java/org/apache/iceberg/gcp/gcs/GCSOutputFile.java#L57-L84","documentation":"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.","triggerScenarios":"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.","commonSituations":"Expired or missing GCP credentials; bucket removed or renamed; transient network/GCS outage; bad path escaping producing an invalid blobId.","solutions":["Check GCS credentials and project/bucket configuration","Verify the bucket and path (blobId) actually exist and are writable","Retry on transient IOException (network flake)","Inspect the chained cause IOException for the root reason"],"exampleFix":"// before\nthrow new RuntimeException(e);\n// after\ntry {\n  PositionOutputStream os = file.createOrOverwrite();\n} catch (UncheckedIOException e) {\n  LOG.error(\"Failed writing to {}\", file.location(), e.getCause());\n  throw e;\n}","handlingStrategy":"retry","validationCode":"// verify bucket exists via storage().get(bucket) and credentials via storage().list(bucket, Storage.BlobListOption.pageSize(1))","typeGuard":null,"tryCatchPattern":"try { os = file.createOrOverwrite(); } catch (UncheckedIOException e) { /* inspect e.getCause(); retry transient failures */ }","preventionTips":["Validate GCP credentials and bucket access before writes","Use paths that avoid escaping/encoding surprises","Retry transient IOExceptions with backoff"],"tags":["gcs","io","unchecked-io"],"backgroundTag":"file-write-failed","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}