{"record":{"id":"42464a2c96286de4","repo":"apache/hadoop","slug":"a-mount-path-file-dir-already-exist-with-the-requ","errorCode":null,"errorMessage":"A mount path(file/dir) already exist with the requested path: <fullPath>","messagePattern":"A mount path\\(file/dir\\) already exist with the requested path: <fullPath>","errorType":"exception","errorClass":"FileAlreadyExistsException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/viewfs/ViewFileSystem.java","lineNumber":1463,"sourceCode":"      throw readOnlyMountTable(\"append\", f);\n    }\n\n    @Override\n    public FSDataOutputStream create(final Path f,\n        final FsPermission permission, final boolean overwrite,\n        final int bufferSize, final short replication, final long blockSize,\n        final Progressable progress) throws IOException {\n      Preconditions.checkNotNull(f, \"File cannot be null.\");\n      if (InodeTree.SlashPath.equals(f)) {\n        throw new FileAlreadyExistsException(\n            \"/ is not a file. The directory / already exist at: \"\n                + theInternalDir.fullPath);\n      }\n\n      if (this.fsState.getRootFallbackLink() != null) {\n\n        if (theInternalDir.getChildren().containsKey(f.getName())) {\n          throw new FileAlreadyExistsException(\n              \"A mount path(file/dir) already exist with the requested path: \"\n                  + theInternalDir.getChildren().get(f.getName()).fullPath);\n        }\n\n        FileSystem linkedFallbackFs =\n            this.fsState.getRootFallbackLink().getTargetFileSystem();\n        Path parent = Path.getPathWithoutSchemeAndAuthority(\n            new Path(theInternalDir.fullPath));\n        String leaf = f.getName();\n        Path fileToCreate = new Path(parent, leaf);\n\n        try {\n          return linkedFallbackFs\n              .create(fileToCreate, permission, overwrite, bufferSize,\n                  replication, blockSize, progress);\n        } catch (IOException e) {\n          LOG.error(\"Failed to create file: {} at fallback: {}\", fileToCreate,\n              linkedFallbackFs.getUri(), e);","sourceCodeStart":1445,"sourceCodeEnd":1481,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/viewfs/ViewFileSystem.java#L1445-L1481","documentation":"When a mount table defines a root fallback link (linkFallback), ViewFileSystem.InternalDir.create(...) forwards creates at internal directories to the fallback file system. It first checks the children of the internal dir: if the file name being created collides with an existing mount point name, it throws FileAlreadyExistsException('A mount path(file/dir) already exist with the requested path: <fullPath>') because the mount entry shadows the fallback file.","triggerScenarios":"linkFallback is configured and the code creates a file directly at an internal directory whose leaf name equals an existing child mount, e.g. mounts define /data/hdfs and the create targets /data with fallback semantics; a merge-like layout where mount names occupy names the application also wants to use as file names.","commonSituations":"Federation mount tables mixing link, linkMerge and linkFallback entries; applications ported from plain HDFS that legitimately created files with names that later became mount point names; mount-table refactors that turned former data dirs into mount names.","solutions":["Write the file under a different leaf name that does not collide with a mount point name","Restructure the mount table so application file names and mount point names do not share the internal directory's namespace","Mount that exact path explicitly (turn it into a real target) instead of relying on the fallback","Pre-check theInternalDir children indirectly: attempt fs.getFileStatus(new Path(parent, leaf)) and treat an existing dir/mount as a naming conflict before create"],"exampleFix":"// before: /data/hdfs is a mount, create(\"/data/hdfs\") with linkFallback -> FileAlreadyExistsException\nFSDataOutputStream out = fs.create(new Path(\"/data/hdfs\"));\n\n// after: choose a non-colliding name or write inside the mount\nFSDataOutputStream out = fs.create(new Path(\"/data/hdfs/newfile\"));\n// or rename the mount in core-site.xml if the name is required for the file","handlingStrategy":"validation","validationCode":"// Detect leaf-name collision with a mount point before create\nPath parent = f.getParent();\nif (fs.exists(new Path(parent, f.getName()))\n    && fs.getFileStatus(new Path(parent, f.getName())).isDirectory()) {\n  throw new IOException(f.getName() + \" collides with a mount point under \" + parent);\n}\nFSDataOutputStream out = fs.create(f);","typeGuard":null,"tryCatchPattern":"try {\n  out = fs.create(f);\n} catch (FileAlreadyExistsException e) {\n  // leaf name equals a mount name in an internal dir with linkFallback\n  out = fs.create(new Path(parent, f.getName() + \".data\"));\n}","preventionTips":["Keep application file names and mount point names in disjoint namespaces under internal dirs","Document linkFallback semantics to authors of mount tables","Prefer writing inside mounts instead of relying on fallback creates"],"tags":["viewfs","hadoop","create","mount-collision","linkfallback"],"backgroundTag":"file-already-exists","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}