{"record":{"id":"7a33b0fc81199888","repo":"apache/iceberg","slug":"path-already-exists-s","errorCode":null,"errorMessage":"Path already exists: %s","messagePattern":"Path already exists: (.+?)","errorType":"exception","errorClass":"AlreadyExistsException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/hadoop/HadoopOutputFile.java","lineNumber":76,"sourceCode":"    return fromPath(path, fs, fs.getConf());\n  }\n\n  public static OutputFile fromPath(Path path, FileSystem fs, Configuration conf) {\n    return new HadoopOutputFile(fs, path, conf);\n  }\n\n  private HadoopOutputFile(FileSystem fs, Path path, Configuration conf) {\n    this.fs = fs;\n    this.path = path;\n    this.conf = conf;\n  }\n\n  @Override\n  public PositionOutputStream create() {\n    try {\n      return HadoopStreams.wrap(fs.create(path, false /* createOrOverwrite */));\n    } catch (FileAlreadyExistsException e) {\n      throw new AlreadyExistsException(e, \"Path already exists: %s\", path);\n    } catch (IOException e) {\n      throw new RuntimeIOException(e, \"Failed to create file: %s\", path);\n    }\n  }\n\n  @Override\n  public PositionOutputStream createOrOverwrite() {\n    try {\n      return HadoopStreams.wrap(fs.create(path, true /* createOrOverwrite */));\n    } catch (IOException e) {\n      throw new RuntimeIOException(e, \"Failed to create file: %s\", path);\n    }\n  }\n\n  public Path getPath() {\n    return path;\n  }\n","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/hadoop/HadoopOutputFile.java#L58-L94","documentation":"HadoopOutputFile.create() opens a stream with createOrOverwrite=false, so Hadoop's FileAlreadyExistsException is converted to Iceberg's AlreadyExistsException with this message. It signals the caller requested a strictly-new file but the path exists.","triggerScenarios":"Calling create() when the target path already exists on the FileSystem (Hadoop fs.create with overwrite=false fails).","commonSituations":"Writing data/manifest files into a location where a same-named file already exists (rerun of a job without cleaning staging, non-unique file names, concurrent writers producing the same path).","solutions":["Use createOrOverwrite() if replacing the file is intended","Generate unique file names per attempt (Iceberg does this via UUIDs/counter in OutputFileFactory)","Check file existence first or clean stale files from the staging directory before retrying","Handle AlreadyExistsException and fall back to a new path"],"exampleFix":"// before\nOutputFile out = io.newOutputFile(path);\nPositionOutputStream s = out.create(); // throws if exists\n// after\nPositionOutputStream s = (overwrite)\n    ? io.newOutputFile(path).createOrOverwrite()\n    : io.newOutputFile(path + \".\" + UUID.randomUUID()).create();","handlingStrategy":"try-catch","validationCode":"Path p = new Path(location);\nif (fs.exists(p)) {\n  throw new org.apache.iceberg.exceptions.AlreadyExistsException(\"Path already exists: %s\", location);\n}","typeGuard":null,"tryCatchPattern":"try { return out.create(); }\ncatch (AlreadyExistsException e) {\n  OutputFile alt = io.newOutputFile(location + \".\" + UUID.randomUUID());\n  return alt.create();\n}","preventionTips":["Generate unique file names per write attempt (UUID/attempt-id)","Clean stale files from staging directories between job retries","Use createOrOverwrite() when replacement is intentional","Avoid concurrent writers targeting identical paths"],"tags":["hadoop","file","conflict"],"backgroundTag":"file-already-exists","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"}