{"record":{"id":"e233da5e031d23cb","repo":"juicedata/juicefs","slug":"file-already-exists-f","errorCode":null,"errorMessage":"File already exists: \" + f","messagePattern":"File already exists: \" \\+ f","errorType":"exception","errorClass":"FileAlreadyExistsException","httpStatus":null,"severity":"error","filePath":"sdk/java/src/main/java/io/juicefs/JuiceFileSystemImpl.java","lineNumber":1505,"sourceCode":"    }\n    return size;\n  }\n\n  @Override\n  public FSDataOutputStream createNonRecursive(Path f, FsPermission permission, EnumSet<CreateFlag> flag,\n                                               int bufferSize, short replication, long blockSize, Progressable progress) throws IOException {\n    if (needCheckPermission() && !checkAncestorAccess(f, FsAction.WRITE, \"createNonRecursive\")) {\n      if (!flag.contains(CreateFlag.OVERWRITE) || !superGroupFileSystem.exists(f)) {\n        return superGroupFileSystem.createNonRecursive(f, permission, flag, bufferSize, replication, blockSize, progress);\n      } else if (!checkPathAccess(f, FsAction.WRITE, \"createNonRecursive\")) {\n        return superGroupFileSystem.createNonRecursive(f, permission, flag, bufferSize, replication, blockSize, progress);\n      }\n    }\n    statistics.incrementWriteOps(1);\n    int fd = lib.jfs_create(Thread.currentThread().getId(), handle, normalizePath(f), permission.toShort(), uMask.toShort());\n    while (fd == EEXIST) {\n      if (!flag.contains(CreateFlag.OVERWRITE) || isDirectory(f)) {\n        throw new FileAlreadyExistsException(\"File already exists: \" + f);\n      }\n      delete(f, false);\n      fd = lib.jfs_create(Thread.currentThread().getId(), handle, normalizePath(f), permission.toShort(), uMask.toShort());\n    }\n    if (fd < 0) {\n      throw error(fd, makeQualified(f).getParent());\n    }\n    return createFsDataOutputStream(f, bufferSize, fd, 0L);\n  }\n\n  private FSDataOutputStream createFsDataOutputStream(Path f, int bufferSize, int fd, long startPosition) throws IOException {\n    FSOutputStream out = new FSOutputStream(fd, f);\n    if (withStreamCapability) {\n      try {\n        return new FSDataOutputStream(\n                (OutputStream) constructor.newInstance(out, checkBufferSize(bufferSize), hflushMethod), statistics, startPosition);\n      } catch (InstantiationException | IllegalAccessException | InvocationTargetException e) {\n        throw new RuntimeException(e);","sourceCodeStart":1487,"sourceCodeEnd":1523,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/sdk/java/src/main/java/io/juicefs/JuiceFileSystemImpl.java#L1487-L1523","documentation":"Thrown by create() when the native jfs_create returns EEXIST and the requested CreateFlag does not include OVERWRITE, or the target is a directory. The file exists and the caller refused overwrite, so the call fails with FileAlreadyExistsException per Hadoop semantics.","triggerScenarios":"create(f, overwrite=false) on an existing file; create with CreateFlag.CREATE only on an existing path; create on an existing directory path; racing create calls to the same path.","commonSituations":"Idempotent writers expecting create to succeed silently; task retries writing the same output file; passing a directory path where a file is expected; Kafka/HBase exporters with fixed file names.","solutions":["Pass overwrite=true or add CreateFlag.OVERWRITE if replacing the file is intended","Delete the existing file before create","Generate unique file names per attempt/task","Catch FileAlreadyExistsException to implement open-if-exists logic"],"exampleFix":"// before\nFSDataOutputStream out = fs.create(path, false);\n// after\nFSDataOutputStream out = fs.create(path, true); // or delete first","handlingStrategy":"try-catch","validationCode":"if (fs.exists(path)) { /* delete or choose new name before create */ }","typeGuard":null,"tryCatchPattern":"try { return fs.create(path, false); } catch (FileAlreadyExistsException e) { /* reuse existing file or delete and recreate */ return fs.open(path); }","preventionTips":["Pass overwrite=true only when replacement is intended","Validate target is not a directory","Use unique output names per task/retry","Catch FileAlreadyExistsException for open-if-exists flows"],"tags":["java","hadoop","file-already-exists"],"backgroundTag":"file-already-exists","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}