{"record":{"id":"afc1e459baef09d4","repo":"apache/iceberg","slug":"file-already-exists-s","errorCode":null,"errorMessage":"File already exists: %s","messagePattern":"File already exists: (.+?)","errorType":"exception","errorClass":"AlreadyExistsException","httpStatus":409,"severity":"error","filePath":"api/src/main/java/org/apache/iceberg/Files.java","lineNumber":59,"sourceCode":"\n  public static OutputFile localOutput(String file) {\n    if (file.startsWith(\"file:\")) {\n      return localOutput(new File(file.replaceFirst(\"file:\", \"\")));\n    }\n    return localOutput(Paths.get(file).toAbsolutePath().toFile());\n  }\n\n  private static class LocalOutputFile implements OutputFile {\n    private final File file;\n\n    private LocalOutputFile(File file) {\n      this.file = file;\n    }\n\n    @Override\n    public PositionOutputStream create() {\n      if (file.exists()) {\n        throw new AlreadyExistsException(\"File already exists: %s\", file);\n      }\n\n      if (!file.getParentFile().isDirectory() && !file.getParentFile().mkdirs()) {\n        throw new RuntimeIOException(\n            \"Failed to create the file's directory at %s.\", file.getParentFile().getAbsolutePath());\n      }\n\n      try {\n        return new PositionFileOutputStream(file, new RandomAccessFile(file, \"rw\"));\n      } catch (FileNotFoundException e) {\n        throw new NotFoundException(e, \"Failed to create file: %s\", file);\n      }\n    }\n\n    @Override\n    public PositionOutputStream createOrOverwrite() {\n      if (file.exists() && !file.delete()) {\n        throw new RuntimeIOException(\"Failed to delete: %s\", file);","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/api/src/main/java/org/apache/iceberg/Files.java#L41-L77","documentation":"Files local FileIO's create() opens a PositionOutputStream for writing and refuses to overwrite: if the target java.io.File already exists it throws AlreadyExistsException to prevent silently clobbering data files or metadata.","triggerScenarios":"Calling fileIO.newOutputFile(location).create() when the file at that location already exists on the local filesystem — e.g. re-running a job that reuses a fixed file path, or a failed earlier attempt left a partial file behind.","commonSituations":"Idempotency violations: fixed filenames in local warehouse directories without uniqueness (UUID/timestamp); retrying a commit after a partial failure; createOrOverwrite used by mistake vs create semantics.","solutions":["Use createOrOverwrite() instead of create() if overwriting is intentional","Generate a unique file name (UUID) per attempt so the path never pre-exists","Delete the stale file (or clean the target directory) before retrying create()"],"exampleFix":"// before\nOutputFile out = fileIO.newOutputFile(path);\nPositionOutputStream stream = out.create();\n// after\nOutputFile out = fileIO.newOutputFile(path);\nPositionOutputStream stream = out.createOrOverwrite();","handlingStrategy":"validation","validationCode":"File f = new File(URI.create(location).getPath());\nPreconditions.checkArgument(!f.exists(), \"File already exists: %s\", f);","typeGuard":null,"tryCatchPattern":"try {\n  stream = outputFile.create();\n} catch (AlreadyExistsException e) {\n  stream = outputFile.createOrOverwrite(); // or generate a new path\n}","preventionTips":["Use unique (UUID) file names per write attempt","Prefer createOrOverwrite() only when overwrite is truly intended","Clean stale partial outputs before retrying jobs"],"tags":["java","fileio","local-filesystem"],"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-14T16:17:12.679Z"}