{"record":{"id":"c89026ac3823da5b","repo":"apache/iceberg","slug":"failed-to-create-output-stream-for-location","errorCode":null,"errorMessage":"Failed to create output stream for location: ","messagePattern":"Failed to create output stream for location: ","errorType":"exception","errorClass":"UncheckedIOException","httpStatus":null,"severity":"error","filePath":"aws/src/main/java/org/apache/iceberg/aws/s3/S3OutputFile.java","lineNumber":75,"sourceCode":"   * 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 S3OutputStream(client(), uri(), s3FileIOProperties(), 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 S3InputFile(client(), asyncClient(), uri(), null, s3FileIOProperties(), metrics());\n  }\n\n  @Override\n  public NativeFileCryptoParameters nativeCryptoParameters() {\n    return nativeEncryptionParameters;\n  }\n\n  @Override\n  public void setNativeCryptoParameters(NativeFileCryptoParameters nativeCryptoParameters) {\n    this.nativeEncryptionParameters = nativeCryptoParameters;\n  }\n}","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/aws/src/main/java/org/apache/iceberg/aws/s3/S3OutputFile.java#L57-L93","documentation":"S3OutputFile.createOrOverwrite() wraps any IOException from constructing the S3OutputStream (e.g. failing to create the local staging file/directory) in an UncheckedIOException with this message. The S3 object upload stream could not even be set up.","triggerScenarios":"Creating the output stream when the configured staging directory is unwritable, missing, or full; File.createTempFile fails due to permissions or disk space.","commonSituations":"s3.staging-dir points to a nonexistent or non-writable path in containers/EMR nodes; /tmp is read-only or full; running with a restricted filesystem in Kubernetes.","solutions":["Check that s3.staging-directory (or the default tmp dir) exists and is writable by the process user.","Fix disk space/permissions on the staging volume.","Inspect the wrapped IOException cause for the root failure.","Point staging to a local ephemeral volume with sufficient capacity."],"exampleFix":"// before\nproperties.put(\"s3.staging-directory\", \"/mnt/nonexistent/staging\");\n// after\nFiles.createDirectories(Paths.get(\"/mnt/staging\"));\nproperties.put(\"s3.staging-directory\", \"/mnt/staging\");","handlingStrategy":"validation","validationCode":"// Java\nFile staging = new File(props.stagingDirectory());\nif (!(staging.exists() || staging.mkdirs()) || !staging.canWrite()) {\n  throw new IllegalStateException(\"Staging dir unusable: \" + staging);\n}","typeGuard":null,"tryCatchPattern":"// Java\ntry {\n  os = outFile.createOrOverwrite();\n} catch (UncheckedIOException e) {\n  LOG.error(\"Staging setup failed: {}\", e.getCause());\n  throw e; // fix staging config; retrying alone won't help\n}","preventionTips":["Pre-create and permission the s3.staging-directory in container/cluster images","Monitor disk space on the staging volume","Never point staging at read-only or NFS-hung mounts"],"tags":["s3","io","staging","unchecked"],"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"}